@octane-xplat/ui 0.9.0 → 0.11.0

package/src/resize-persist.web.ts

@@ -0,0 +1,38 @@
+/** Resizable `autoSaveId` persistence — localStorage on web. Three legacy
+ *  formats are read like upstream's: a bare number, `{ size }` alone, and
+ *  `{ size, isCollapsed }` where size may be null while collapsed. */
+export interface PersistedResizableState {
+	size?: number | null
+	isCollapsed?: boolean
+}
+
+export function loadResizableState(key: string): PersistedResizableState | null {
+	try {
+		const raw = window.localStorage.getItem(key)
+		if (raw == null) {
+			return null
+		}
+
+		const parsed = JSON.parse(raw)
+		if (typeof parsed === 'number') {
+			return { size: parsed }
+		}
+
+		if (typeof parsed === 'object' && parsed !== null) {
+			const size = typeof parsed.size === 'number' ? parsed.size : null
+			return { size, isCollapsed: parsed.isCollapsed === true }
+		}
+
+		return null
+	} catch {
+		return null
+	}
+}
+
+export function persistResizableState(key: string, state: PersistedResizableState): void {
+	try {
+		window.localStorage.setItem(key, JSON.stringify(state))
+	} catch {
+		// Quota/SSR failures are non-fatal — persistence is best-effort.
+	}
+}

package/src/resize-state.ts

@@ -0,0 +1,338 @@
+import type {
+	ResizableConfig,
+	ResizableDirection,
+	ResizableRegion,
+	ResizableProps,
+	UseResizableSingleConfig,
+} from './props'
+
+import { clampSize, toPixels } from './resize-math'
+import { loadResizableState, persistResizableState } from './resize-persist'
+
+export const DEFAULT_COLLAPSED_SIZE = 40
+
+/** Platform seam the machine needs: measure the % basis and observe it for
+ *  changes. Each leaf supplies these so the state machine stays platform-free. */
+export interface ResizableBasisSource {
+	/** Current basis in px/dips for the axis (container size, or the
+	 *  viewport/screen when no container is supplied). */
+	measure: (
+		containerRef: { current: any } | undefined,
+		direction: ResizableDirection,
+	) => number | null
+	/** Subscribe to basis changes; returns an unsubscribe. */
+	observe: (
+		containerRef: { current: any } | undefined,
+		direction: ResizableDirection,
+		cb: () => void,
+	) => () => void
+	/** Storage key prefix — `astryx-resizable:` upstream. */
+	storagePrefix: string
+}
+
+/** One resizable region's machine — plain object so multi-region use and
+ *  per-platform hooks stay thin. Re-entrant gesture handlers mirror the
+ *  upstream hook exactly. */
+export interface ResizableMachine {
+	region: ResizableRegion
+	/** Recompute bounds when the measured basis changed. */
+	remeasure: () => void
+	/** Push new config (props changed between renders). */
+	update: (config: UseResizableSingleConfig) => void
+	subscribe: (cb: () => void) => () => void
+	/** Snapshot for getSnapshot — a fresh object only when size/collapsed change. */
+	getSnapshot: () => { size: number; isCollapsed: boolean }
+}
+
+const warned = new Set<string>()
+function devWarn(what: string, msg: string) {
+	const k = what + ':' + msg
+	if (warned.has(k)) {
+		return
+	}
+
+	warned.add(k)
+	console.warn(`[octane-xplat] ${what}: ${msg}`)
+}
+
+/** Build a single resizable region. `storageKey` defaults to autoSaveId;
+ *  multi-region callers pass `${autoSaveId}:${key}`. */
+export function createResizableRegion(
+	config: UseResizableSingleConfig,
+	basis: ResizableBasisSource,
+	storageKey?: string,
+): ResizableMachine {
+	const direction: ResizableDirection = config.direction ?? 'horizontal'
+	const containerRef = config.containerRef
+	const persistKey = storageKey ?? config.autoSaveId
+	const persisted = persistKey
+		? loadResizableState(
+				persistKey.startsWith(basis.storagePrefix) ? persistKey : basis.storagePrefix + persistKey,
+			)
+		: null
+
+	let listeners = new Set<() => void>()
+	let gestureBasis: number | null = null
+	let dragStartSize = 0
+	let didWarnInverted = false
+	let snapshot = { size: 0, isCollapsed: false }
+
+	const emit = () => {
+		listeners.forEach((cb) => cb())
+	}
+
+	let cfg = config
+	let basisValue: number | null = basis.measure(containerRef, direction)
+	const isBasisMeasured = () => basisValue != null
+
+	const resolvedMin = () => {
+		const v = toPixels(cfg.minSize, basisValue ?? 0)
+		return v ?? 0
+	}
+
+	const resolvedMax = () => {
+		const v = toPixels(cfg.maxSize, basisValue ?? Infinity)
+		return v ?? Infinity
+	}
+
+	const snaps = () => cfg.snaps ?? []
+
+	const initialSize = () => {
+		if (persisted?.size != null) {
+			return persisted.size
+		}
+
+		const d = toPixels(cfg.defaultSize, basisValue ?? 0)
+		return d ?? 0
+	}
+
+	let chosenSize = initialSize()
+	let uncontrolledCollapsed = persisted?.isCollapsed ?? cfg.defaultIsCollapsed ?? false
+
+	const isControlled = () => cfg.isCollapsed !== undefined
+	const isCollapsed = () =>
+		cfg.collapsible ? (isControlled() ? cfg.isCollapsed! : uncontrolledCollapsed) : false
+
+	const recomputeSnapshot = () => {
+		const size = isCollapsed() ? 0 : chosenSize
+		if (snapshot.size !== size || snapshot.isCollapsed !== isCollapsed()) {
+			snapshot = { size, isCollapsed: isCollapsed() }
+		}
+	}
+
+	recomputeSnapshot()
+
+	const setCollapsed = (value: boolean) => {
+		if (!isControlled()) {
+			uncontrolledCollapsed = value
+		}
+	}
+
+	const notify = () => {
+		if (resolvedMin() > resolvedMax() && !didWarnInverted) {
+			didWarnInverted = true
+			devWarn(
+				'useResizable',
+				`the resolved minimum (${resolvedMin()}px) is above the resolved maximum (${resolvedMax()}px). The maximum wins.`,
+			)
+		}
+
+		if (persistKey && isBasisMeasured()) {
+			persistResizableState(
+				persistKey.startsWith(basis.storagePrefix) ? persistKey : basis.storagePrefix + persistKey,
+				{ size: chosenSize, isCollapsed: isCollapsed() },
+			)
+		}
+
+		recomputeSnapshot()
+		emit()
+	}
+
+	const collapse = () => {
+		if (!cfg.collapsible || isCollapsed()) {
+			return
+		}
+
+		setCollapsed(true)
+		cfg.onCollapseChange?.(true)
+		cfg.onSizeChange?.(0)
+		notify()
+	}
+
+	const expand = () => {
+		const wasCollapsed = isCollapsed()
+		setCollapsed(false)
+		if (wasCollapsed) {
+			cfg.onCollapseChange?.(false)
+		}
+
+		cfg.onSizeChange?.(chosenSize)
+		notify()
+	}
+
+	const resize = (newSize: number) => {
+		if (!Number.isFinite(newSize) || newSize < 0) {
+			devWarn(
+				'useResizable',
+				`resize(${String(newSize)}) is not a pixel size. Keeping the current size. Percentages configure the hook; they are not a programmatic input.`,
+			)
+
+			return
+		}
+
+		const clamped = clampSize(newSize, resolvedMin(), resolvedMax(), snaps())
+		const wasCollapsed = isCollapsed()
+		chosenSize = clamped
+		setCollapsed(false)
+		if (wasCollapsed) {
+			cfg.onCollapseChange?.(false)
+		}
+
+		cfg.onSizeChange?.(clamped)
+		notify()
+	}
+
+	const onResizeStart = () => {
+		gestureBasis = basisValue
+		dragStartSize = isCollapsed() ? 0 : chosenSize
+	}
+
+	const onResizeMove = (delta: number) => {
+		const raw = dragStartSize + delta
+		const collapsedSize = cfg.collapsedSize ?? DEFAULT_COLLAPSED_SIZE
+		if (cfg.collapsible && raw < collapsedSize) {
+			if (!isCollapsed()) {
+				setCollapsed(true)
+				cfg.onCollapseChange?.(true)
+				cfg.onSizeChange?.(0)
+				notify()
+			}
+
+			return
+		}
+
+		if (isCollapsed() && raw >= collapsedSize) {
+			setCollapsed(false)
+			cfg.onCollapseChange?.(false)
+		}
+
+		const clamped = clampSize(raw, resolvedMin(), resolvedMax(), snaps())
+		chosenSize = clamped
+		cfg.onSizeChange?.(clamped)
+		notify()
+	}
+
+	const releaseGestureBasis = () => {
+		gestureBasis = null
+	}
+
+	const onResizeEnd = () => {
+		releaseGestureBasis()
+	}
+
+	const props: ResizableProps = {
+		_size: 0,
+		_isCollapsed: false,
+		_onResizeStart: onResizeStart,
+		_onResizeMove: onResizeMove,
+		_onResizeEnd: onResizeEnd,
+		_onResizeCancel: releaseGestureBasis,
+		_minSizePx: 0,
+		_maxSizePx: 0,
+		_snaps: [],
+		_collapsedSize: 0,
+		_collapsible: false,
+		_direction: direction,
+		_isResizableProps: true,
+	}
+
+	const syncProps = () => {
+		props._size = isCollapsed() ? 0 : chosenSize
+		props._isCollapsed = isCollapsed()
+		props._minSizePx = resolvedMin()
+		props._maxSizePx = resolvedMax()
+		props._snaps = snaps()
+		props._collapsedSize = cfg.collapsedSize ?? DEFAULT_COLLAPSED_SIZE
+		props._collapsible = cfg.collapsible ?? false
+	}
+
+	syncProps()
+
+	const machine: ResizableMachine = {
+		region: {
+			size: snapshot.size,
+			isCollapsed: snapshot.isCollapsed,
+			collapse,
+			expand,
+			resize,
+			props,
+		},
+		subscribe: (cb) => {
+			listeners.add(cb)
+			return () => listeners.delete(cb)
+		},
+		getSnapshot: () => {
+			recomputeSnapshot()
+			syncProps()
+			// Keep the public region object in step with the snapshot.
+			machine.region.size = snapshot.size
+			machine.region.isCollapsed = snapshot.isCollapsed
+			return snapshot
+		},
+		remeasure: () => {
+			if (gestureBasis != null) {
+				return
+			} // frozen mid-gesture
+
+			const next = basis.measure(containerRef, direction)
+			if (next == null || next === basisValue) {
+				return
+			}
+
+			basisValue = next
+			// Re-resolve the selection against the new basis.
+			chosenSize = clampSize(chosenSize, resolvedMin(), resolvedMax(), snaps())
+			notify()
+		},
+		update: (next: UseResizableSingleConfig) => {
+			// Silent config swap — emitting here would re-render the component
+			// every frame (update is called during render, notifying subscribers
+			// loops). Config reads happen lazily via cfg.* at gesture time.
+			cfg = next
+		},
+	}
+
+	// First layout resolution — the basis may arrive after mount.
+	if (!isBasisMeasured()) {
+		// The caller's observe() path calls remeasure once the element reports.
+	} else {
+		notify()
+	}
+
+	return machine
+}
+
+/** Map a component's simplified `resizable` config (e.g. SideNav) to the
+ *  full single-region config. */
+export function regionConfigFrom(
+	resizable: true | ResizableConfig | undefined,
+): UseResizableSingleConfig | null {
+	if (!resizable) {
+		return null
+	}
+
+	if (resizable === true) {
+		return { defaultSize: 260, minSize: 180, maxSize: 480 }
+	}
+
+	return {
+		defaultSize: resizable.defaultWidth ?? 260,
+		minSize: resizable.minWidth ?? 180,
+		maxSize: resizable.maxWidth ?? 480,
+		autoSaveId: resizable.autoSaveId,
+		defaultIsCollapsed: resizable.defaultIsCollapsed,
+		isCollapsed: resizable.isCollapsed,
+		onSizeChange: resizable.onWidthChange,
+		onCollapseChange: resizable.onCollapseChange,
+	}
+}

package/src/root-layout.web.ts

@@ -0,0 +1,16 @@
+/** Native RootLayout instances have no counterpart in the DOM renderer. */
+export function registerRootLayout(_layout: unknown): void {}
+
+export function unregisterRootLayout(_layout: unknown): void {}
+
+export function topRootLayout(): undefined {
+	return undefined
+}
+
+export function rootLayoutFor(_view: unknown): undefined {
+	return undefined
+}
+
+export function findInRootLayouts(_id: string): null {
+	return null
+}

package/src/route-android.test.ts

@@ -74,7 +74,7 @@ vi.mock('@nativescript-community/octane', () => ({
 	},
 }))
 
-vi.mock('./route-host.mobile', () => ({ RouteHost: () => null }))
+vi.mock('./route-host', () => ({ RouteHost: () => null }))
 vi.mock('./stacks', async () => import('./stacks.ts'))
 let router: typeof import('./route')
 let stacks: typeof import('./stacks')

package/src/route-history.web.test.ts

@@ -78,3 +78,39 @@ it('loads a direct URL without adding history or running its guard', async () =>
 	expect(guard).not.toHaveBeenCalled()
 	expect(loader).toHaveBeenCalledTimes(1)
 })
+
+it('marks a hydrating loader pending until it settles', async () => {
+	let resolve!: (value: unknown) => void
+	const loader = vi.fn(() => new Promise((yes) => (resolve = yes)))
+	history.replaceState(null, '', '/baked')
+	router.registerRoutes(defineRoutes([{ path: 'baked', screen: () => null, loader }]))
+
+	expect(router.routeFor('root')).toMatchObject({ name: 'baked', loaderPending: true })
+	// hydrateRoute schedules the loader on a microtask — let it fire.
+	await settle()
+	expect(loader).toHaveBeenCalledTimes(1)
+	resolve({ entries: ['baked'] })
+	await settle()
+	expect(router.routeFor('root')).toMatchObject({
+		loaderData: { entries: ['baked'] },
+		loaderPending: false,
+	})
+})
+
+it('marks a rejected hydrating loader pending until it settles to an error', async () => {
+	let reject!: (error: unknown) => void
+	const loader = vi.fn(() => new Promise((_, no) => (reject = no)))
+	history.replaceState(null, '', '/baked')
+	router.registerRoutes(defineRoutes([{ path: 'baked', screen: () => null, loader }]))
+
+	expect(router.routeFor('root')?.loaderPending).toBe(true)
+	await settle()
+	expect(loader).toHaveBeenCalledTimes(1)
+	reject(new Error('offline'))
+	await settle()
+	expect(router.routeFor('root')).toMatchObject({
+		loaderPending: false,
+	})
+
+	expect((router.routeFor('root')!.loaderError as Error).message).toBe('offline')
+})

package/src/route-host.ts

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

package/src/route-navigation.web.test.ts

@@ -25,7 +25,7 @@ vi.mock('./stacks', () => ({
 	stackEntries: () => new Map().entries(),
 }))
 
-vi.mock('./route-host.mobile', () => ({ RouteHost: () => null }))
+vi.mock('./route-host', () => ({ RouteHost: () => null }))
 
 function deferred<T>() {
 	let resolve!: (value: T) => void

package/src/route-scroll.web.test.ts

@@ -0,0 +1,142 @@
+// @vitest-environment jsdom
+import { beforeEach, expect, it, vi } from 'vitest'
+import { defineRoutes } from './route-table'
+vi.mock('octane', () => ({ useSyncExternalStore: vi.fn() }))
+
+// Scroll restoration contract (route.web): a push starts at the top — or at
+// the element a `hash` names — pop/forward restores the position saved for
+// that history entry, and a modal push overlays without touching it.
+let router: typeof import('./route.web')
+let scrollTo: ReturnType<typeof vi.spyOn>
+let pos = 0
+
+beforeEach(async () => {
+	vi.resetModules()
+	vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => setTimeout(() => cb(0), 0))
+
+	pos = 0
+	Object.defineProperty(window, 'scrollY', { get: () => pos, configurable: true })
+	scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
+	history.replaceState(null, '', '/')
+	document.body.innerHTML = ''
+	router = await import('./route.web')
+	router.registerRoutes(
+		defineRoutes([
+			{ path: 'detail', screen: () => null },
+			{ path: 'list', screen: () => null },
+			{ path: 'about', screen: () => null, presentation: 'modal' },
+		]),
+	)
+})
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 25))
+
+it('starts a push at the top', async () => {
+	pos = 300
+	await settle() // boot settle
+	scrollTo.mockClear()
+
+	router.pushRoute({ stack: 'root', name: 'detail', params: {} })
+	await settle()
+	expect(scrollTo).toHaveBeenCalledWith(0, 0)
+})
+
+it('restores the saved position on pop and the newer one on forward', async () => {
+	router.pushRoute({ stack: 'root', name: 'detail', params: {} })
+	await settle()
+	pos = 300
+	router.pushRoute({ stack: 'root', name: 'list', params: {} })
+	await settle()
+	pos = 0 // landed at the top of 'list'
+	scrollTo.mockClear()
+
+	history.back()
+	await settle()
+	expect(scrollTo).toHaveBeenCalledWith(0, 300)
+
+	scrollTo.mockClear()
+	history.forward()
+	await settle()
+	expect(scrollTo).toHaveBeenCalledWith(0, 0)
+})
+
+it('keeps independent positions for entries sharing a URL', async () => {
+	router.pushRoute({ stack: 'root', name: 'detail', params: {} })
+	await settle()
+	pos = 111
+	router.pushRoute({ stack: 'root', name: 'detail', params: {} })
+	await settle()
+	pos = 222 // scrolled inside the second entry
+	scrollTo.mockClear()
+
+	history.back()
+	await settle()
+	expect(scrollTo).toHaveBeenCalledWith(0, 111)
+
+	scrollTo.mockClear()
+	history.forward()
+	await settle()
+	expect(scrollTo).toHaveBeenCalledWith(0, 222)
+})
+
+it('scrolls a pushed hash to its element instead of the top', async () => {
+	document.body.innerHTML = '<div id="section">target</div>'
+	const target = document.getElementById('section')!
+	target.scrollIntoView = vi.fn()
+	await settle()
+	scrollTo.mockClear()
+
+	router.pushRoute({ stack: 'root', name: 'detail', params: {}, hash: 'section' })
+	await settle()
+	expect(location.hash).toBe('#section')
+	expect(target.scrollIntoView).toHaveBeenCalled()
+	expect(scrollTo).not.toHaveBeenCalledWith(0, 0)
+})
+
+it('does not restore a saved position over a hash target on pop', async () => {
+	document.body.innerHTML = '<div id="section">target</div>'
+	const target = document.getElementById('section')!
+	target.scrollIntoView = vi.fn()
+	router.pushRoute({ stack: 'root', name: 'detail', params: {}, hash: 'section' })
+	await settle()
+	pos = 400 // scrolled past the anchor
+	router.pushRoute({ stack: 'root', name: 'list', params: {} })
+	await settle()
+	scrollTo.mockClear()
+	const scrollIntoView = target.scrollIntoView as ReturnType<typeof vi.fn>
+	scrollIntoView.mockClear()
+
+	history.back()
+	await settle()
+	// The position saved for the entry wins over its hash.
+	expect(scrollTo).toHaveBeenCalledWith(0, 400)
+	expect(scrollIntoView).not.toHaveBeenCalled()
+})
+
+it('leaves the position alone when a modal route pushes over it', async () => {
+	router.pushRoute({ stack: 'root', name: 'detail', params: {} })
+	await settle()
+	pos = 150
+	scrollTo.mockClear()
+
+	router.pushRoute({ stack: 'root', name: 'about', params: {} })
+	await settle()
+	expect(router.currentModalRoute()?.name).toBe('about')
+	expect(scrollTo).not.toHaveBeenCalled()
+})
+
+it('keys positions by URL when an entry predates registration', async () => {
+	// Boot on /list with no route table — the entry has no stamped id, so
+	// its position keys on the URL (path+query+hash).
+	history.replaceState(null, '', '/list?filter=unread#deep')
+	router.registerRoutes(defineRoutes([{ path: 'list', screen: () => null }]))
+	pos = 250
+	router.pushRoute({ stack: 'root', name: 'detail', params: {} })
+	await settle()
+	pos = 0
+	scrollTo.mockClear()
+
+	history.back()
+	await settle()
+	expect(scrollTo).toHaveBeenCalledWith(0, 250)
+})