@octane-xplat/ui 0.6.0 → 0.7.0

package/src/route.web.ts

@@ -0,0 +1,366 @@
+import { useSyncExternalStore } from 'octane'
+
+/** Web route store — the browser half of the nav contract. One linear URL
+ *  stack; `stack` names the conceptual outlet ('root' covers the app, a
+ *  named stack is the pane that owns it — parallel stacks map to nested
+ *  routes). URL shape: /<stack>/<path>?query or /<path>?query for root,
+ *  where <path> comes from the route-dir manifest — `app/demo/[id].tsrx`
+ *  pushes as /demo/<id-value>. Names not in the manifest keep the legacy
+ *  /<name>?params shape. Module-scope like every other store — the pane
+ *  that owns `stack` subscribes with useRoute(stack) and swaps content.
+ *
+ *  Modal routes (presentation 'modal' — `+modal` route files or a
+ *  pushRoute override) push a real URL but overlay instead of replacing:
+ *  `current` keeps the underlying route, `modalRoute` carries the modal.
+ *  Back (popstate or popRoute) dismisses it. */
+
+export type { Route } from './props'
+import type { Route, RouteHead, RouteManifest, RouteMeta, ScreenTable } from './props'
+import {
+	buildRoutePath,
+	layoutChain,
+	linkPath,
+	matchUrl,
+	mergeRouteManifests,
+	RouteRedirect,
+} from './route-table'
+
+// ---------- screen registry ----------
+
+// Effective tables = the file-derived base manifest merged under every
+// addRoutes layer. Keeping the split means an HMR re-run of routes.gen.*
+// (registerRoutes again) can't wipe routes an app added at runtime.
+let baseManifest: RouteManifest = { screens: {}, routes: [], layouts: {} }
+const dynamicManifests: RouteManifest[] = []
+let screens: ScreenTable = {}
+let routes: RouteMeta[] = []
+let routeLayouts: Record<string, any> = {}
+let routeLoaders: NonNullable<RouteManifest['loaders']> = {}
+
+function rebuildRegistry(): void {
+	const merged = mergeRouteManifests(baseManifest, ...dynamicManifests)
+	screens = merged.screens
+	routes = merged.routes
+	routeLayouts = merged.layouts
+	routeLoaders = merged.loaders ?? {}
+	// Registration can land after the first lazy parse (deep link read
+	// before the routes module ran) — re-parse with patterns present.
+	if (current !== undefined) {
+		current = parse()
+		emit()
+	}
+}
+
+/** Register the app's name → screen table. On web the table feeds
+ *  `screenFor` — the fallback outlet resolution in Tabs when no
+ *  `resolveScreen` prop is given; on native `pushRoute` resolves
+ *  `route.name` through it. `manifest` (from deriveRouteManifest) enables
+ *  path-param matching — call once from the shared routes module. */
+export function registerScreens(table: ScreenTable, manifest?: RouteMeta[]): void {
+	baseManifest = { ...baseManifest, screens: table, routes: manifest ?? [] }
+	rebuildRegistry()
+}
+
+/** One-call registration for route-dir apps — screens + URL patterns +
+ *  layouts all come from deriveRouteManifest. */
+export function registerRoutes(manifest: RouteManifest): void {
+	baseManifest = manifest
+	rebuildRegistry()
+	applyHead(read())
+}
+
+/** Layer a programmatic manifest (from `defineRoutes`) over the registered
+ *  routes — same-name entries win over the base with a warn, so a host
+ *  framework can override a file route deliberately. Registered layers
+ *  survive later registerRoutes re-registration (e.g. routes.gen HMR). */
+export function addRoutes(manifest: RouteManifest): void {
+	dynamicManifests.push(manifest)
+	rebuildRegistry()
+	applyHead(read())
+}
+
+export function screenFor(name: string): ScreenTable[string] | undefined {
+	return screens[name]
+}
+
+/** Directory layouts wrapping a route, outermost → innermost — outlets
+ *  wrap their resolved element with these (`_layout.tsrx` files). */
+export function layoutsFor(name: string): any[] {
+	return layoutChain(routeLayouts, name)
+}
+
+export { layoutsFor as layoutsForRoute }
+
+// ---------- the store ----------
+
+const listeners = new Set<() => void>()
+// Lazy — the manifest registers after this module evaluates, and parse()
+// needs its patterns for path params.
+let current: Route | null | undefined
+let modalRoute: Route | null = null
+let historyDepth = history.state?.__octaneXplatDepth ?? 0
+
+const ROUTE_HEAD_ATTR = 'data-octane-xplat-route-head'
+
+// Scroll positions keyed by URL — restored on popstate (native keeps
+// stack pages alive, so only the web leaf needs this). `lastKey` is the
+// outgoing URL: popstate fires after location already changed, so the
+// saved position must be written under the URL we just left.
+const scrollPositions = new Map<string, number>()
+let lastKey = location.pathname + location.search
+const scrollKey = () => location.pathname + location.search
+const saveScroll = () => scrollPositions.set(lastKey, window.scrollY)
+const restoreScroll = () => {
+	const y = scrollPositions.get(scrollKey())
+	if (y !== undefined) {
+		requestAnimationFrame(() => window.scrollTo(0, y))
+	}
+}
+
+function parse(): Route | null {
+	return matchUrl(routes, location.pathname + location.search)
+}
+
+function read(): Route | null {
+	if (current === undefined) {
+		current = parse()
+	}
+
+	return current
+}
+
+function emit() {
+	listeners.forEach((l) => l())
+}
+
+function metaFor(name: string): RouteMeta | undefined {
+	return routes.find((meta) => meta.name === name)
+}
+
+function headFor(r: Route | null): RouteHead | undefined {
+	const head = r ? metaFor(r.name)?.head : undefined
+	return typeof head === 'function' ? head(r?.params ?? {}) : head
+}
+
+function applyHead(r: Route | null): void {
+	if (typeof document === 'undefined') {
+		return
+	}
+
+	const head = headFor(r)
+	if (!head) {
+		document.querySelectorAll(`meta[${ROUTE_HEAD_ATTR}]`).forEach((node) => node.remove())
+		return
+	}
+
+	if (head.title !== undefined) {
+		document.title = head.title
+	}
+
+	document.querySelectorAll(`meta[${ROUTE_HEAD_ATTR}]`).forEach((node) => node.remove())
+	for (const [name, content] of Object.entries(head.meta ?? {})) {
+		const tag = document.createElement('meta')
+		tag.setAttribute('name', name)
+		tag.setAttribute('content', content)
+		tag.setAttribute(ROUTE_HEAD_ATTR, '')
+		document.head.appendChild(tag)
+	}
+}
+
+function contextFor(r: Route): Record<string, unknown> {
+	return r.context ?? {}
+}
+
+async function prepareRoute(r: Route, redirects = 0): Promise<void> {
+	const beforeLoad = metaFor(r.name)?.beforeLoad
+	if (!beforeLoad) {
+		commitRoute(r)
+		return
+	}
+
+	if (redirects > 16) {
+		console.warn(`[octane-xplat] beforeLoad redirect loop for '${r.name}'`)
+		return
+	}
+
+	try {
+		const returned = await beforeLoad({ params: r.params, context: contextFor(r) })
+		const context = returned ? { ...contextFor(r), ...returned } : contextFor(r)
+		commitRoute({
+			...r,
+			context,
+		})
+	} catch (e) {
+		if (e instanceof RouteRedirect) {
+			await prepareRoute(e.route, redirects + 1)
+			return
+		}
+
+		console.warn(`[octane-xplat] beforeLoad('${r.name}') rejected: ${(e as Error)?.message ?? e}`)
+	}
+}
+
+export function redirect(r: Route): never {
+	throw new RouteRedirect(r)
+}
+
+export function pushRoute(r: Route): void {
+	if (metaFor(r.name)?.beforeLoad) {
+		void prepareRoute(r)
+		return
+	}
+
+	commitRoute(r)
+}
+
+function commitRoute(r: Route): void {
+	const route: Route = { ...r, presentation: r.presentation ?? presentationFor(r.name) }
+	const loader = routeLoaders[route.name] ?? routes.find((meta) => meta.name === route.name)?.loader
+	if (
+		loader &&
+		!Object.prototype.hasOwnProperty.call(route, 'loaderData') &&
+		!Object.prototype.hasOwnProperty.call(route, 'loaderError')
+	) {
+		void Promise.resolve()
+			.then(() => loader(route.params))
+			.then(
+				(loaderData) => commitRoute({ ...route, loaderData }),
+				(loaderError) => commitRoute({ ...route, loaderError }),
+			)
+
+		return
+	}
+
+	saveScroll()
+	historyDepth += 1
+	history.pushState({ __octaneXplatDepth: historyDepth }, '', buildRoutePath(routes, route))
+	lastKey = scrollKey()
+	if (route.presentation === 'modal') {
+		modalRoute = route
+	} else {
+		current = route
+		modalRoute = null
+	}
+
+	applyHead(modalRoute ?? current ?? null)
+	emit()
+}
+
+function presentationFor(name: string): Route['presentation'] {
+	return routes.find((m) => m.name === name)?.presentation
+}
+
+/** Web history is one linear stack — back pops whatever route is current;
+ *  per-stack pops aren't expressible, so `stack` is accepted for parity
+ *  and ignored. A pushed modal is the top entry, so back dismisses it. */
+export function popRoute(_stack = 'root'): void {
+	history.back()
+}
+
+let backInterceptorWarned = false
+
+/** No-op twin of the native leaf. Browser back is already real history —
+ *  there is no hardware-back event to intercept on web, so registered
+ *  interceptors never fire. Warns once so a mistaken call site isn't
+ *  silently absent. */
+export function addBackInterceptor(_fn: () => boolean): () => void {
+	if (!backInterceptorWarned) {
+		backInterceptorWarned = true
+		console.warn(
+			'[octane-xplat] addBackInterceptor is a no-op on web — browser back is URL history, not an interceptable event.',
+		)
+	}
+
+	return () => {}
+}
+
+window.addEventListener('popstate', () => {
+	saveScroll()
+	historyDepth = history.state?.__octaneXplatDepth ?? 0
+	lastKey = scrollKey()
+	modalRoute = null
+	current = parse()
+	applyHead(current)
+	restoreScroll()
+	emit()
+})
+
+/** Current route if it targets `stack`, else null. */
+export function routeFor(stack: string): Route | null {
+	const c = read()
+	return c && c.stack === stack ? c : null
+}
+
+/** Web has one linear browser history; expose its active route stack for parity. */
+export function routeStacks(): string[] {
+	const route = read()
+	return route ? [route.stack] : []
+}
+
+/** The route active at boot — for deep-link tab selection. */
+export function currentRoute(): Route | null {
+	return read()
+}
+
+/** The modal route overlaying the current one, if any. */
+export function currentModalRoute(): Route | null {
+	return modalRoute
+}
+
+/** Deep-link entry, web half — the URL *is* the route state, so this is a
+ *  plain pushRoute of the matched path (parity with the native leaf, where
+ *  apps wire `onDeepLink(pushDeepLink)`). */
+export function pushDeepLink(url: string): boolean {
+	const r = matchUrl(routes, linkPath(url))
+	if (!r) {
+		console.warn(`[octane-xplat] pushDeepLink('${url}') dropped — no route matches.`)
+		return false
+	}
+
+	pushRoute(r)
+	return true
+}
+
+/** URL for a Route — Link's href and shareable-path helper. */
+export function hrefFor(r: Route): string {
+	return buildRoutePath(routes, r)
+}
+
+export function useRoute(stack: string): Route | null {
+	return useSyncExternalStore(
+		(cb) => {
+			listeners.add(cb)
+			return () => listeners.delete(cb)
+		},
+		() => routeFor(stack),
+	)
+}
+
+/** Whether the selected conceptual stack has an in-app route to pop. A
+ * browser's pre-app history is intentionally not counted. */
+export function canGoBack(stack = 'root'): boolean {
+	const route = read()
+	return historyDepth > 0 && route?.stack === stack
+}
+
+export function useCanGoBack(stack = 'root'): boolean {
+	return useSyncExternalStore(
+		(cb) => {
+			listeners.add(cb)
+			return () => listeners.delete(cb)
+		},
+		() => canGoBack(stack),
+	)
+}
+
+/** The modal route overlaying the shell — outlets render it above their
+ *  normal content (URL preserved underneath). */
+export function useModalRoute(): Route | null {
+	return useSyncExternalStore(
+		(cb) => {
+			listeners.add(cb)
+			return () => listeners.delete(cb)
+		},
+		() => modalRoute,
+	)
+}

package/src/safeAreaInsets.macos.tsrx

@@ -0,0 +1,7 @@
+import type { SafeAreaInsets } from './props'
+
+/** The AppKit root view begins below the title bar; there are no additional
+ * safe-area insets in this window-hosted renderer. */
+export function useSafeAreaInsets(): SafeAreaInsets {
+	return { top: 0, right: 0, bottom: 0, left: 0 }
+}

package/src/safeAreaInsets.tsrx

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'octane';
+import { Application, Screen } from '@nativescript/core';
+
+export interface SafeAreaInsets { top: number; right: number; bottom: number; left: number; }
+
+function androidActivity(): any {
+	return Application.android?.foregroundActivity ?? Application.android?.startActivity;
+}
+
+function readAndroidInsets(): SafeAreaInsets {
+	const decorView = androidActivity()?.getWindow?.()?.getDecorView?.();
+	const insets = decorView?.getRootWindowInsets?.();
+	if (!insets) return { top: 0, right: 0, bottom: 0, left: 0 };
+
+	const scale = Screen.mainScreen.scale || 1;
+	if (android.os.Build.VERSION.SDK_INT >= 30) {
+		const systemBars =
+			android.view.WindowInsets.Type.systemBars() | android.view.WindowInsets.Type.displayCutout();
+
+		const i = insets.getInsets(systemBars);
+		return {
+			top: i.top / scale,
+			right: i.right / scale,
+			bottom: i.bottom / scale,
+			left: i.left / scale,
+		};
+	}
+
+	return {
+		top: insets.getSystemWindowInsetTop() / scale,
+		right: insets.getSystemWindowInsetRight() / scale,
+		bottom: insets.getSystemWindowInsetBottom() / scale,
+		left: insets.getSystemWindowInsetLeft() / scale,
+	};
+}
+
+function measure(): SafeAreaInsets {
+	const view = Application.ios?.rootController?.view;
+	const insets = view?.safeAreaInsets;
+	if (insets) return { top: insets.top, right: insets.right, bottom: insets.bottom, left: insets.left };
+	if (Application.android) return readAndroidInsets();
+	return { top: 0, right: 0, bottom: 0, left: 0 };
+}
+
+/** Reads the root view's insets; Android and pre-attachment reads may be zero. */
+export function useSafeAreaInsets(): SafeAreaInsets {
+	const [insets, setInsets] = useState<SafeAreaInsets>(measure);
+	useEffect(() => {
+		const update = () => setInsets(measure());
+		Application.on(Application.orientationChangedEvent, update);
+		Application.on(Application.resumeEvent, update);
+		update();
+		return () => {
+			Application.off(Application.orientationChangedEvent, update);
+			Application.off(Application.resumeEvent, update);
+		};
+	}, []);
+
+	return insets;
+}

package/src/safeAreaInsets.web.tsrx

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'octane';
+
+export interface SafeAreaInsets { top: number; right: number; bottom: number; left: number; }
+
+function measure(): SafeAreaInsets {
+	if (!document.body) return { top: 0, right: 0, bottom: 0, left: 0 };
+	const probe = document.createElement('div');
+	probe.style.cssText = 'position:fixed;visibility:hidden;pointer-events:none;' +
+		'padding:env(safe-area-inset-top) env(safe-area-inset-right) ' +
+		'env(safe-area-inset-bottom) env(safe-area-inset-left);' +
+		'padding:constant(safe-area-inset-top) constant(safe-area-inset-right) ' +
+		'constant(safe-area-inset-bottom) constant(safe-area-inset-left);';
+
+	document.body.appendChild(probe);
+	const style = getComputedStyle(probe);
+	const insets = {
+		top: parseFloat(style.paddingTop) || 0,
+		right: parseFloat(style.paddingRight) || 0,
+		bottom: parseFloat(style.paddingBottom) || 0,
+		left: parseFloat(style.paddingLeft) || 0,
+	};
+
+	probe.remove();
+	return insets;
+}
+
+/** Approximate CSS safe-area values, measured on mount and viewport resize. */
+export function useSafeAreaInsets(): SafeAreaInsets {
+	const [insets, setInsets] = useState<SafeAreaInsets>({ top: 0, right: 0, bottom: 0, left: 0 });
+	useEffect(() => {
+		const update = () => setInsets(measure());
+		update();
+		window.addEventListener('resize', update);
+		return () => window.removeEventListener('resize', update);
+	}, []);
+
+	return insets;
+}

package/src/sheet-detents.ts

@@ -0,0 +1,142 @@
+import { FlexboxLayout, Screen } from '@nativescript/core'
+import { detentOffset, normalizeDetents, snapDetentIndex } from './sheet-snap'
+
+const SNAP_MS = 200
+
+export interface SheetDetentsController {
+	/** Slide the panel in from below the screen edge — call once the host
+	 *  is inside the RootLayout (the RootLayout open call replaces the
+	 *  built-in enter/exit animation, which would fight detent offsets:
+	 *  it always animates translateY to 0). */
+	enter: () => void
+	detach: () => void
+}
+
+/** Drag-to-snap detents on a RootLayout sheet host: a self-drawn grabber
+ *  strip (top-aligned grid child — the only drag target, so it never
+ *  fights inner scrolling) drives the host's translateY; the host 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` via RootLayout 'closed',
+ *  or the `openSheet` resolution).
+ *
+ *  In-window on native: the OS detent presentations
+ *  (UISheetPresentationController / BottomSheetBehavior via
+ *  BottomSheetDialogFragment) host a modal VC or a separate dialog
+ *  window — a different surface contract than the RootLayout child this
+ *  sheet is (UIModal/MaterialDialog own the modal path), so the snap
+ *  mechanics are self-drawn and identical to the web leaf. */
+export function attachSheetDetents(
+	host: any,
+	detents: readonly number[],
+	closeNow: () => void,
+): SheetDetentsController {
+	const sorted = normalizeDetents(detents)
+	if (!sorted.length) {
+		return { detach: () => {}, enter: () => {} }
+	}
+
+	// Parentless at attach (before RootLayout.open) — fall back to screen
+	// dips; every gesture-time read uses the real parent height.
+	const vh = () => (host.parent?.getActualSize?.().height || Screen.mainScreen.heightDIPs)
+	const max = sorted[sorted.length - 1]
+	let cur = 0
+
+	host.verticalAlignment = 'bottom'
+	host.translateY = vh() // fully below the screen until enter()
+
+	const grabber = new FlexboxLayout()
+	grabber.className = 'vx-sheet-grabber'
+	grabber.verticalAlignment = 'top'
+	const grip = new FlexboxLayout()
+	grip.className = 'vx-sheet-grip'
+	grabber.addChild(grip)
+	host.addChild(grabber)
+
+	let dragging = false
+	let dy0 = 0 // pan deltaY baseline — the gesture reports cumulative deltas
+	let ty0 = 0
+	let vy = 0
+	let lastDy = 0
+	let lastT = 0
+
+	const animateTo = (value: number, then?: () => void) => {
+		const done = host.animate?.({ translate: { x: 0, y: value }, duration: SNAP_MS })
+		if (!then) {
+			return
+		}
+
+		if (done?.then) {
+			done.then(() => then())
+		} else {
+			setTimeout(then, SNAP_MS)
+		}
+	}
+
+	const end = () => {
+		if (!dragging) {
+			return
+		}
+
+		dragging = false
+		const next = snapDetentIndex(host.translateY, vy, sorted, vh())
+		if (next < 0) {
+			animateTo(vh(), closeNow)
+		} else {
+			cur = next
+			animateTo(detentOffset(sorted, cur, vh()))
+		}
+	}
+
+	const onPan = (e: any) => {
+		if (e.state === 1) {
+			// began
+			dragging = true
+			dy0 = e.deltaY
+			ty0 = host.translateY
+			vy = 0
+			lastDy = e.deltaY
+			lastT = Date.now()
+			return
+		}
+
+		if (e.state === 0 || e.state === 3) {
+			// cancelled / ended
+			end()
+			return
+		}
+
+		if (!dragging) {
+			return
+		}
+
+		const now = Date.now()
+		const dt = (now - lastT) / 1000
+		const inc = e.deltaY - lastDy
+		if (dt > 0) {
+			vy = vy * 0.7 + (inc / dt) * 0.3
+		}
+
+		lastDy = e.deltaY
+		lastT = now
+		host.translateY = Math.min(Math.max(ty0 + (e.deltaY - dy0), 0), vh())
+	}
+
+	grabber.on('pan', onPan)
+
+	return {
+		enter: () => {
+			// Size the panel now that the host has a parent — grabber row
+			// heights and detent fractions resolve against the RootLayout.
+			host.height = max * vh()
+			host.translateY = vh()
+			animateTo(detentOffset(sorted, cur, vh()))
+		},
+		detach: () => {
+			grabber.off('pan', onPan)
+			if (grabber.parent === host) {
+				host.removeChild?.(grabber)
+			}
+		},
+	}
+}