@octane-xplat/ui 0.7.3 → 0.10.0

package/src/route.web.ts

@@ -1,3 +1,4 @@
+import { createNavigationRequests, type NavigationRequest } from './navigation-request'
 import { useSyncExternalStore } from 'octane'
 
 /** Web route store — the browser half of the nav contract. One linear URL
@@ -27,6 +28,8 @@ import {
 
 // ---------- screen registry ----------
 
+const navigationRequests = createNavigationRequests()
+
 // 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.
@@ -46,7 +49,7 @@ function rebuildRegistry(): void {
 	// 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()
+		restoreRouteState()
 		emit()
 	}
 }
@@ -66,7 +69,8 @@ export function registerScreens(table: ScreenTable, manifest?: RouteMeta[]): voi
 export function registerRoutes(manifest: RouteManifest): void {
 	baseManifest = manifest
 	rebuildRegistry()
-	applyHead(read())
+	read()
+	applyHead(modalRoute ?? current ?? null)
 }
 
 /** Layer a programmatic manifest (from `defineRoutes`) over the registered
@@ -76,13 +80,20 @@ export function registerRoutes(manifest: RouteManifest): void {
 export function addRoutes(manifest: RouteManifest): void {
 	dynamicManifests.push(manifest)
 	rebuildRegistry()
-	applyHead(read())
+	read()
+	applyHead(modalRoute ?? current ?? null)
 }
 
 export function screenFor(name: string): ScreenTable[string] | undefined {
 	return screens[name]
 }
 
+/** The route's declared `ErrorBoundary` export, if any — outlets wrap the
+ *  resolved screen in `RouteBoundary` with it. */
+export function errorBoundaryFor(name: string): any {
+	return metaFor(name)?.errorBoundary
+}
+
 /** Directory layouts wrapping a route, outermost → innermost — outlets
  *  wrap their resolved element with these (`_layout.tsrx` files). */
 export function layoutsFor(name: string): any[] {
@@ -100,33 +111,185 @@ let current: Route | null | undefined
 let modalRoute: Route | null = null
 let historyDepth = history.state?.__octaneXplatDepth ?? 0
 
+// History stores an identity rather than loader results: loaders may return
+// values that structured clone cannot serialize. Retain the prepared route
+// for this document's back/forward traversal; fresh boots still parse the URL.
+const historyRoutes = new Map<string, { current: Route | null; modal: Route | null }>()
+const historyEntryPrefix = Math.random().toString(36).slice(2)
+let nextHistoryEntry = 0
+
+function rememberRouteState(entry = historyEntryPrefix + ':' + ++nextHistoryEntry): string {
+	historyRoutes.set(entry, { current: current ?? null, modal: modalRoute })
+	return entry
+}
+
+function restoreRouteState(): void {
+	const saved = historyRoutes.get(history.state?.__octaneXplatEntry)
+	if (saved) {
+		current = saved.current
+		modalRoute = saved.modal
+	} else {
+		const route = parse()
+		modalRoute = route?.presentation === 'modal' ? route : null
+		current = modalRoute ? null : route
+		if (route) {
+			hydrateRoute(route)
+		}
+
+		// A parsed (never-committed) entry has no prepared scroll state —
+		// a boot hash lands here once the screen mounts.
+		scrollTick += 1
+		settleScroll(true)
+	}
+}
+
+// Direct URLs and history entries from a previous document have no prepared
+// loader result. Run their loader without pushing another history entry or
+// changing the documented bootstrap guard boundary.
+function hydrateRoute(route: Route): void {
+	const loader = routeLoaders[route.name] ?? metaFor(route.name)?.loader
+	if (
+		!loader ||
+		Object.prototype.hasOwnProperty.call(route, 'loaderData') ||
+		Object.prototype.hasOwnProperty.call(route, 'loaderError')
+	) {
+		return
+	}
+
+	// The screen is already mounted — mark the in-flight load so it can
+	// render `pending` until `data`/`error` arrive.
+	route.loaderPending = true
+	const finish = (result: Pick<Route, 'loaderData' | 'loaderError'>) => {
+		const prepared = { ...route, ...result, loaderPending: false }
+		let changed = false
+		if (current === route) {
+			current = prepared
+			changed = true
+		}
+
+		if (modalRoute === route) {
+			modalRoute = prepared
+			changed = true
+		}
+
+		for (const saved of historyRoutes.values()) {
+			if (saved.current === route) {
+				saved.current = prepared
+			}
+
+			if (saved.modal === route) {
+				saved.modal = prepared
+			}
+		}
+
+		if (changed) {
+			emit()
+		}
+	}
+
+	void Promise.resolve()
+		.then(() => loader(route.params))
+		.then(
+			(loaderData) => finish({ loaderData }),
+			(loaderError) => finish({ loaderError }),
+		)
+}
+
 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.
+// Scroll restoration — the web half of the scroll contract (native keeps
+// stack pages alive, so only this leaf needs it). Positions are keyed by
+// the history-entry id we stamp into history.state — two entries sharing
+// a URL keep independent positions — with the URL (path+query+hash) as
+// the fallback key for entries that predate registration.
+//
+//   push        → top of document, or the element the route's `hash` names
+//   pop/forward → the position saved for that entry (then hash, then top)
+//   modal push  → overlay — the underlying position is left untouched
+//
+// `lastKey` tracks the outgoing entry: popstate fires after location
+// already changed, so the position must be written under the entry we
+// just left.
+if (typeof history !== 'undefined' && 'scrollRestoration' in history) {
+	// The browser's own scroll restoration would race ours on traversal
+	// and reload — the contract above owns scroll instead.
+	history.scrollRestoration = 'manual'
+}
+
 const scrollPositions = new Map<string, number>()
-let lastKey = location.pathname + location.search
-const scrollKey = () => location.pathname + location.search
+const scrollKey = () =>
+	(history.state?.__octaneXplatEntry as string | undefined) ??
+	location.pathname + location.search + location.hash
+
+let lastKey = scrollKey()
 const saveScroll = () => scrollPositions.set(lastKey, window.scrollY)
-const restoreScroll = () => {
-	const y = scrollPositions.get(scrollKey())
-	if (y !== undefined) {
-		requestAnimationFrame(() => window.scrollTo(0, y))
+
+function scrollToHash(hash: string): boolean {
+	const id = hash.slice(1)
+	if (!id) {
+		return false
+	}
+
+	let decoded = id
+	try {
+		decoded = decodeURIComponent(id)
+	} catch {
+		// keep the raw fragment — malformed input just misses the lookup
 	}
+
+	const target = document.getElementById(decoded)
+	if (!target) {
+		return false
+	}
+
+	target.scrollIntoView()
+	return true
+}
+
+// Settles carry the navigation they're for: `scrollTick` advances on every
+// commit/traversal, and a queued settle drops itself when a newer navigation
+// superseded it — otherwise a settle scheduled just before a push could fire
+// on the new entry and fight the push's own scroll. Key and hash are
+// captured at schedule time for the same reason — popstate has already
+// moved `location` when the handler runs, but a queued settle can outlive
+// one more commit.
+let scrollTick = 0
+
+// Defer to rAF so the newly resolved screen has mounted before we measure
+// or scroll it — a still-mounting hash target simply misses to top.
+function settleScroll(restore: boolean): void {
+	const tick = scrollTick
+	const key = scrollKey()
+	const hash = location.hash
+	requestAnimationFrame(() => {
+		if (tick !== scrollTick) {
+			return
+		}
+
+		if (restore) {
+			const y = scrollPositions.get(key)
+			if (y !== undefined) {
+				window.scrollTo(0, y)
+				return
+			}
+		}
+
+		if (!scrollToHash(hash)) {
+			window.scrollTo(0, 0)
+		}
+	})
 }
 
 function parse(): Route | null {
-	return matchUrl(routes, location.pathname + location.search)
+	return matchUrl(routes, location.pathname + location.search + location.hash)
 }
 
 function read(): Route | null {
 	if (current === undefined) {
-		current = parse()
+		restoreRouteState()
 	}
 
-	return current
+	return current ?? null
 }
 
 function emit() {
@@ -171,10 +334,14 @@ function contextFor(r: Route): Record<string, unknown> {
 	return r.context ?? {}
 }
 
-async function prepareRoute(r: Route, redirects = 0): Promise<void> {
+async function prepareRoute(r: Route, request: NavigationRequest, redirects = 0): Promise<void> {
+	if (!request.isCurrent()) {
+		return
+	}
+
 	const beforeLoad = metaFor(r.name)?.beforeLoad
 	if (!beforeLoad) {
-		commitRoute(r)
+		commitRoute(r, request)
 		return
 	}
 
@@ -186,13 +353,20 @@ async function prepareRoute(r: Route, redirects = 0): Promise<void> {
 	try {
 		const returned = await beforeLoad({ params: r.params, context: contextFor(r) })
 		const context = returned ? { ...contextFor(r), ...returned } : contextFor(r)
-		commitRoute({
-			...r,
-			context,
-		})
+		commitRoute(
+			{
+				...r,
+				context,
+			},
+			request,
+		)
 	} catch (e) {
+		if (!request.isCurrent()) {
+			return
+		}
+
 		if (e instanceof RouteRedirect) {
-			await prepareRoute(e.route, redirects + 1)
+			await prepareRoute(e.route, request, redirects + 1)
 			return
 		}
 
@@ -205,15 +379,20 @@ export function redirect(r: Route): never {
 }
 
 export function pushRoute(r: Route): void {
+	const request = navigationRequests.begin('history')
 	if (metaFor(r.name)?.beforeLoad) {
-		void prepareRoute(r)
+		void prepareRoute(r, request)
 		return
 	}
 
-	commitRoute(r)
+	commitRoute(r, request)
 }
 
-function commitRoute(r: Route): void {
+function commitRoute(r: Route, request: NavigationRequest): void {
+	if (!request.isCurrent()) {
+		return
+	}
+
 	const route: Route = { ...r, presentation: r.presentation ?? presentationFor(r.name) }
 	const loader = routeLoaders[route.name] ?? routes.find((meta) => meta.name === route.name)?.loader
 	if (
@@ -224,17 +403,30 @@ function commitRoute(r: Route): void {
 		void Promise.resolve()
 			.then(() => loader(route.params))
 			.then(
-				(loaderData) => commitRoute({ ...route, loaderData }),
-				(loaderError) => commitRoute({ ...route, loaderError }),
+				(loaderData) => commitRoute({ ...route, loaderData }, request),
+				(loaderError) => commitRoute({ ...route, loaderError }, request),
 			)
 
 		return
 	}
 
+	read()
+	// Include the entry we are leaving, even if it was the initial URL —
+	// the replace also mints its entry id, so its scroll position saves
+	// under the same key a later popstate will look up.
+	history.replaceState(
+		{
+			...history.state,
+			__octaneXplatDepth: historyDepth,
+			__octaneXplatEntry: rememberRouteState(history.state?.__octaneXplatEntry),
+		},
+		'',
+	)
+
+	lastKey = scrollKey()
 	saveScroll()
+
 	historyDepth += 1
-	history.pushState({ __octaneXplatDepth: historyDepth }, '', buildRoutePath(routes, route))
-	lastKey = scrollKey()
 	if (route.presentation === 'modal') {
 		modalRoute = route
 	} else {
@@ -242,8 +434,24 @@ function commitRoute(r: Route): void {
 		modalRoute = null
 	}
 
+	history.pushState(
+		{ __octaneXplatDepth: historyDepth, __octaneXplatEntry: rememberRouteState() },
+		'',
+		buildRoutePath(routes, route),
+	)
+
+	lastKey = scrollKey()
+
 	applyHead(modalRoute ?? current ?? null)
 	emit()
+	// A push starts at the top — or the hash target — of the new document.
+	// A modal overlays the current entry instead, so it leaves the
+	// underlying position untouched. The tick still advances so a stale
+	// settle doesn't fire on the modal entry.
+	scrollTick += 1
+	if (route.presentation !== 'modal') {
+		settleScroll(false)
+	}
 }
 
 function presentationFor(name: string): Route['presentation'] {
@@ -254,6 +462,7 @@ function presentationFor(name: string): Route['presentation'] {
  *  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 {
+	navigationRequests.invalidate('history')
 	history.back()
 }
 
@@ -274,16 +483,27 @@ export function addBackInterceptor(_fn: () => boolean): () => void {
 	return () => {}
 }
 
-window.addEventListener('popstate', () => {
+// Singletoned like the native back-press wiring: under vite HMR this
+// module's state resets but its popstate listener must not duplicate —
+// the handler delegates through a slot so a reloaded module graph swaps
+// in fresh closures instead of double-settling.
+const host = window as any
+host.__octaneXplatPopstate = () => {
+	navigationRequests.invalidate('history')
 	saveScroll()
 	historyDepth = history.state?.__octaneXplatDepth ?? 0
 	lastKey = scrollKey()
-	modalRoute = null
-	current = parse()
-	applyHead(current)
-	restoreScroll()
+	restoreRouteState()
+	applyHead(modalRoute ?? current ?? null)
+	scrollTick += 1
+	settleScroll(true)
 	emit()
-})
+}
+
+if (!host.__octaneXplatRouteWired) {
+	host.__octaneXplatRouteWired = true
+	window.addEventListener('popstate', () => host.__octaneXplatPopstate?.())
+}
 
 /** Current route if it targets `stack`, else null. */
 export function routeFor(stack: string): Route | null {
@@ -304,6 +524,7 @@ export function currentRoute(): Route | null {
 
 /** The modal route overlaying the current one, if any. */
 export function currentModalRoute(): Route | null {
+	read()
 	return modalRoute
 }
 
@@ -312,7 +533,7 @@ export function currentModalRoute(): Route | null {
  *  apps wire `onDeepLink(pushDeepLink)`). */
 export function pushDeepLink(url: string): boolean {
 	const r = matchUrl(routes, linkPath(url))
-	if (!r) {
+	if (!r || !screenFor(r.name)) {
 		console.warn(`[octane-xplat] pushDeepLink('${url}') dropped — no route matches.`)
 		return false
 	}
@@ -339,7 +560,8 @@ export function useRoute(stack: string): Route | null {
 /** 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()
+	read()
+	const route = modalRoute ?? current
 	return historyDepth > 0 && route?.stack === stack
 }
 

package/src/safe-url.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizeUrl } from './safe-url'
+
+describe('sanitizeUrl', () => {
+	it('blocks script and HTML data schemes, including control-character obfuscation', () => {
+		expect(sanitizeUrl('javascript:alert(1)')).toBeNull()
+		expect(sanitizeUrl('java\nscript:alert(1)')).toBeNull()
+		expect(sanitizeUrl('data:text/html,<script>')).toBeNull()
+	})
+
+	it('keeps ordinary web URLs unchanged', () => {
+		expect(sanitizeUrl('https://example.com/path?q=1')).toBe('https://example.com/path?q=1')
+	})
+})

package/src/safe-url.ts

@@ -0,0 +1,28 @@
+// Navigation URL safety — ported from Astryx's utils/safeUrl.ts. Blocks the
+// schemes that execute script in a link href; every other value passes
+// through normalized (control chars stripped) rather than rewritten.
+
+function normalizeUrl(url: string): string {
+	// oxlint-disable-next-line no-control-regex -- Strip controls before URL-scheme checks.
+	return url.replace(/[\x00-\x1f\x7f]/g, '').trim()
+}
+
+/** Return the normalized URL, or null for a blocked scheme. */
+export function sanitizeUrl(url: string): string | null {
+	const normalized = normalizeUrl(url)
+	const lower = normalized.toLowerCase()
+	if (
+		lower.startsWith('javascript:') ||
+		lower.startsWith('vbscript:') ||
+		lower.startsWith('data:text/html')
+	) {
+		return null
+	}
+
+	return normalized
+}
+
+/** Inspect a navigation string without changing the value used by its sink. */
+export function isSafeUrl(url: string): boolean {
+	return sanitizeUrl(url) !== null
+}

package/src/scheme-colors.ts

@@ -0,0 +1,53 @@
+// Concrete semantic colors for native text runs — FormattedString spans and
+// property-set colors don't resolve `var(--color-*)`, so leaves that paint
+// text directly mirror the chrome.css palette here (light values in :root,
+// dark values in the .dark block; danger/warning/success are scheme-stable
+// there). Resolve with `useColorScheme()`/`getColorScheme()` from
+// './theme/colorScheme'.
+export type Scheme = 'light' | 'dark'
+
+const TEXT_SECONDARY: Record<Scheme, string> = { light: '#666666', dark: '#a1a1a1' }
+const TEXT_PRIMARY: Record<Scheme, string> = { light: '#0a0a0a', dark: '#ededed' }
+const PRIMARY: Record<Scheme, string> = { light: '#171717', dark: '#ededed' }
+const SUCCESS = '#15803d'
+const WARNING = '#b45309'
+const DANGER = '#dc2626'
+
+export const mutedColor = (scheme: Scheme) => TEXT_SECONDARY[scheme]
+export const textColor = (scheme: Scheme) => TEXT_PRIMARY[scheme]
+export const accentColor = (scheme: Scheme) => PRIMARY[scheme]
+export const successColor = () => SUCCESS
+export const warningColor = () => WARNING
+export const dangerColor = () => DANGER
+
+/** StatusDot variant → ink color painted on the dot on native. */
+export function statusDotColor(variant: string, scheme: Scheme): string {
+	switch (variant) {
+		case 'success':
+			return SUCCESS
+		case 'warning':
+			return WARNING
+		case 'error':
+			return DANGER
+		case 'accent':
+			return PRIMARY[scheme]
+		default:
+			return TEXT_SECONDARY[scheme]
+	}
+}
+
+/** ProgressBar variant → fill color on native. */
+export function progressFillColor(variant: string, scheme: Scheme): string {
+	switch (variant) {
+		case 'success':
+			return SUCCESS
+		case 'warning':
+			return WARNING
+		case 'error':
+			return DANGER
+		case 'neutral':
+			return TEXT_SECONDARY[scheme]
+		default:
+			return PRIMARY[scheme]
+	}
+}

package/src/select-options.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { filterSelectOptions, groupSelectOptions, toggleVisibleSelection } from './select-options'
+
+describe('finite-list selection data', () => {
+	it('keeps disabled and hidden selections during filtered bulk toggles', () => {
+		const shown = [{ value: 'a' }, { value: 'locked', isDisabled: true }]
+		expect(toggleVisibleSelection(['hidden', 'locked'], shown)).toEqual(['hidden', 'locked', 'a'])
+		expect(toggleVisibleSelection(['hidden', 'locked', 'a'], shown)).toEqual(['hidden', 'locked'])
+	})
+
+	it('filters supporting groups by the same label/value predicate used for navigation', () => {
+		const options = [
+			{ value: 'a', label: 'Apple', group: 'Fruit' },
+			{ value: 'b', label: 'Berlin', group: 'Cities' },
+			{ value: 'c', label: 'Banana', group: 'Fruit' },
+		]
+
+		expect(
+			groupSelectOptions(filterSelectOptions(options, 'A')).flatMap((group) =>
+				group.options.map((option) => option.value),
+			),
+		).toEqual(['a', 'c'])
+	})
+})

package/src/select-options.ts

@@ -0,0 +1,43 @@
+import type { SelectOption } from './props'
+
+export function selectValues(value: string | string[] | null | undefined): string[] {
+	return value == null ? [] : Array.isArray(value) ? [...new Set(value)] : [value]
+}
+
+export function sameSelection(a: string[], b: string[]): boolean {
+	return a.length === b.length && a.every((value, index) => value === b[index])
+}
+
+export function filterSelectOptions(options: SelectOption[], query: string): SelectOption[] {
+	const lower = query.toLowerCase()
+	return options.filter((option) => (option.label ?? option.value).toLowerCase().includes(lower))
+}
+
+export function groupSelectOptions(
+	options: SelectOption[],
+): { heading: string | undefined; options: SelectOption[] }[] {
+	const groups = new Map<string | undefined, SelectOption[]>()
+	for (const option of options) {
+		const rows = groups.get(option.group)
+		if (rows) {
+			rows.push(option)
+		} else {
+			groups.set(option.group, [option])
+		}
+	}
+
+	return [...groups].map(([heading, rows]) => ({ heading, options: rows }))
+}
+
+/** Bulk toggles affect only the visible enabled set, retaining hidden/disabled values. */
+export function toggleVisibleSelection(selected: string[], options: SelectOption[]): string[] {
+	const enabled = options.filter((option) => !option.isDisabled).map((option) => option.value)
+	if (!enabled.length) {
+		return selected
+	}
+
+	const allSelected = enabled.every((value) => selected.includes(value))
+	return allSelected
+		? selected.filter((value) => !enabled.includes(value))
+		: [...new Set([...selected, ...enabled])]
+}