@octane-xplat/ui 0.6.0 → 0.7.1

package/src/route-table.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it } from 'vitest'
+import {
+	buildRoutePath,
+	defineRoutes,
+	deriveRouteManifest,
+	layoutChain,
+	linkPath,
+	matchRoute,
+	matchUrl,
+	mergeRouteManifests,
+} from './route-table'
+
+const C = (n: string) => Object.assign(() => null, { displayName: n })
+
+function manifest(files: Record<string, any>, prefer: string[] = ['web']) {
+	return deriveRouteManifest(files, prefer)
+}
+
+describe('deriveRouteManifest', () => {
+	it('maps file paths to route names', () => {
+		const m = manifest({
+			'./app/detail.tsrx': { Detail: C('Detail') },
+			'./app/demo/[id].tsrx': { DemoDetail: C('DemoDetail') },
+			'./app/chat/index.tsrx': { Chat: C('Chat') },
+		})
+
+		expect(Object.keys(m.screens).sort()).toEqual(['chat', 'demo/:id', 'detail'])
+		const demo = m.routes.find((r) => r.name === 'demo/:id')!
+		expect(demo.segments).toEqual(['demo', ':id'])
+		expect(demo.params).toEqual(['id'])
+	})
+
+	it('keeps _layout files out of screens and catalogs them by dir', () => {
+		const m = manifest({
+			'./app/_layout.tsrx': { Root: C('Root') },
+			'./app/chat/_layout.tsrx': { ChatShell: C('ChatShell') },
+			'./app/detail.tsrx': { Detail: C('Detail') },
+		})
+
+		expect(Object.keys(m.screens)).toEqual(['detail'])
+		expect(m.layouts[''].displayName).toBe('Root')
+		expect(m.layouts['chat'].displayName).toBe('ChatShell')
+	})
+
+	it('prefers platform variants; skips other platforms entirely', () => {
+		const files = {
+			'./app/settings.tsrx': { S: C('shared') },
+			'./app/settings.web.tsrx': { S: C('web') },
+			'./app/settings.mobile.tsrx': { S: C('mobile') },
+			'./app/only.tsrx': { O: C('only') },
+		}
+
+		const web = manifest(files, ['web'])
+		expect(web.screens.settings.displayName).toBe('web')
+		const mobile = manifest(files, ['ios', 'mobile'])
+		expect(mobile.screens.settings.displayName).toBe('mobile')
+	})
+
+	it('skips a suffix that is not in the prefer list', () => {
+		const m = manifest({ './app/x.ios.tsrx': { X: C('x') } }, ['android', 'mobile'])
+		expect(m.screens.x).toBeUndefined()
+	})
+
+	it('picks default export, then screen, then single function export', () => {
+		const m = manifest({
+			'./app/a.tsrx': { default: C('d'), other: C('o') },
+			'./app/b.tsrx': { screen: C('s'), helper: () => 1 },
+			'./app/c.tsrx': { only: C('only') },
+		})
+
+		expect(m.screens.a.displayName).toBe('d')
+		expect(m.screens.b.displayName).toBe('s')
+		expect(m.screens.c.displayName).toBe('only')
+	})
+})
+
+describe('matchRoute + buildRoutePath', () => {
+	const { routes } = manifest({
+		'./app/detail.tsrx': { D: C('D') },
+		'./app/demo/[id].tsrx': { DD: C('DD') },
+		'./app/demo/new.tsrx': { DN: C('DN') },
+	})
+
+	it('static beats param at the same depth', () => {
+		expect(matchRoute(routes, ['demo', 'new'])!.meta.name).toBe('demo/new')
+		expect(matchRoute(routes, ['demo', 'x'])!.meta.name).toBe('demo/:id')
+	})
+
+	it('extracts path params', () => {
+		const hit = matchRoute(routes, ['demo', 'counter'])!
+		expect(hit.params).toEqual({ id: 'counter' })
+	})
+
+	it('builds path with substituted params; leftovers go to query', () => {
+		expect(
+			buildRoutePath(routes, {
+				stack: 'demos',
+				name: 'demo/:id',
+				params: { id: 'counter', tab: '2' },
+			}),
+		).toBe('/demos/demo/counter?tab=2')
+
+		expect(
+			buildRoutePath(routes, { stack: 'root', name: 'detail', params: { from: 'home' } }),
+		).toBe('/detail?from=home')
+	})
+
+	it('non-manifest names keep the legacy shape', () => {
+		expect(buildRoutePath(routes, { stack: 'root', name: 'other', params: { a: '1' } })).toBe(
+			'/other?a=1',
+		)
+	})
+
+	it('JSON-encodes non-scalar params and restores them on match', () => {
+		const path = buildRoutePath(routes, {
+			stack: 'root',
+			name: 'detail',
+			params: { filter: { unread: true } },
+		})
+
+		const matched = matchUrl(routes, path)!
+
+		expect(path).toContain('json%3A%7B%22unread%22%3Atrue%7D')
+		expect(matched.params.filter).toEqual({ unread: true })
+	})
+
+	it('strips a +presentation suffix into meta.presentation', () => {
+		const m = manifest({
+			'./app/settings+modal.tsrx': { S: C('S') },
+			'./app/fade+fade.tsrx': { F: C('F') },
+		})
+
+		expect(m.screens.settings.displayName).toBe('S')
+		expect(m.routes.find((r) => r.name === 'settings')!.presentation).toBe('modal')
+		expect(m.routes.find((r) => r.name === 'fade')!.presentation).toBe('fade')
+	})
+
+	it('presentation suffix composes with platform suffixes', () => {
+		const m = manifest(
+			{
+				'./app/sheet+modal.tsrx': { S: C('shared') },
+				'./app/sheet+modal.mobile.tsrx': { S: C('mobile') },
+			},
+			['ios', 'mobile'],
+		)
+
+		expect(m.screens.sheet.displayName).toBe('mobile')
+		expect(m.routes[0].name).toBe('sheet')
+		expect(m.routes[0].presentation).toBe('modal')
+	})
+
+	it('picks up a loader export; loader-only files have no screen', () => {
+		const loader = (p: Record<string, unknown>) => p
+		const m = manifest({
+			'./app/detail.tsrx': { screen: C('D'), loader },
+			'./app/data.tsrx': { loader },
+		})
+
+		expect(m.routes.find((r) => r.name === 'detail')!.loader).toBe(loader)
+		expect(m.screens.data).toBeUndefined()
+	})
+
+	it('records beforeLoad and head exports without mistaking them for screens', () => {
+		const beforeLoad = () => ({ role: 'member' })
+		const head = (params: Record<string, unknown>) => ({ title: String(params.id) })
+		const m = manifest({
+			'./app/detail.tsrx': { Detail: C('D'), beforeLoad, head },
+		})
+
+		const detail = m.routes[0]
+
+		expect(detail.beforeLoad).toBe(beforeLoad)
+		expect(detail.head).toBe(head)
+		expect(m.screens.detail.displayName).toBe('D')
+	})
+})
+
+describe('matchUrl + linkPath', () => {
+	const { routes } = manifest({
+		'./app/detail.tsrx': { D: C('D') },
+		'./app/demo/[id].tsrx': { DD: C('DD') },
+		'./app/settings+modal.tsrx': { S: C('S') },
+	})
+
+	it('root path wins over stack interpretation', () => {
+		expect(matchUrl(routes, '/demo/x')).toMatchObject({ stack: 'root', name: 'demo/:id' })
+	})
+
+	it('first segment is the stack when the whole path misses', () => {
+		const r = matchUrl(routes, '/demos/demo/x?tab=2')!
+		expect(r).toMatchObject({ stack: 'demos', name: 'demo/:id' })
+		expect(r.params).toEqual({ id: 'x', tab: '2' })
+	})
+
+	it('carries meta.presentation into the route', () => {
+		expect(matchUrl(routes, '/settings')!.presentation).toBe('modal')
+	})
+
+	it('normalizes http(s) and app-scheme URLs', () => {
+		expect(linkPath('https://x.com/demo/9?a=1')).toBe('/demo/9?a=1')
+		expect(linkPath('textcoral://demo/9')).toBe('/demo/9')
+		expect(linkPath('/demo/9')).toBe('/demo/9')
+	})
+})
+
+describe('layoutChain', () => {
+	const m = manifest({
+		'./app/_layout.tsrx': { Root: C('Root') },
+		'./app/chat/_layout.tsrx': { ChatShell: C('ChatShell') },
+		'./app/chat/room.tsrx': { Room: C('Room') },
+		'./app/detail.tsrx': { D: C('D') },
+	})
+
+	it("chains ancestor dir layouts, outermost first, '' excluded", () => {
+		expect(layoutChain(m.layouts, 'chat/room').map((c) => c.displayName)).toEqual(['ChatShell'])
+		expect(layoutChain(m.layouts, 'detail')).toEqual([])
+		expect(layoutChain(m.layouts, 'chat')).toEqual([])
+	})
+})
+
+describe('defineRoutes', () => {
+	it('turns path specs into metas + screens, sorted by specificity', () => {
+		const m = defineRoutes({
+			routes: [
+				{ path: 'guides/:slug', screen: C('Guide') },
+				{ path: 'guides', screen: C('GuideIndex') },
+				{ path: 'guides/new', screen: C('NewGuide') },
+			],
+		})
+
+		expect(Object.keys(m.screens).sort()).toEqual(['guides', 'guides/:slug', 'guides/new'])
+		expect(m.routes.map((r) => r.name)).toEqual(['guides/new', 'guides/:slug', 'guides'])
+		const guide = m.routes.find((r) => r.name === 'guides/:slug')!
+		expect(guide.segments).toEqual(['guides', ':slug'])
+		expect(guide.params).toEqual(['slug'])
+	})
+
+	it('accepts [param] syntax, a bare array, and index/empty paths', () => {
+		const m = defineRoutes([
+			{ path: 'docs/[slug]', screen: C('Doc') },
+			{ path: 'docs/index', screen: C('DocIndex') },
+			{ path: '', screen: C('Root') },
+		])
+
+		expect(m.screens['docs/:slug'].displayName).toBe('Doc')
+		expect(m.screens.docs.displayName).toBe('DocIndex')
+		expect(m.screens.index.displayName).toBe('Root')
+	})
+
+	it('carries presentation, loader, beforeLoad, and head onto the meta', () => {
+		const loader = (p: Record<string, unknown>) => p
+		const beforeLoad = () => ({ ok: true })
+		const head = { title: 'Doc' }
+		const m = defineRoutes([
+			{
+				path: 'doc',
+				screen: C('Doc'),
+				presentation: 'modal',
+				loader,
+				beforeLoad,
+				head,
+			},
+		])
+
+		const meta = m.routes[0]
+		expect(meta.presentation).toBe('modal')
+		expect(meta.loader).toBe(loader)
+		expect(meta.beforeLoad).toBe(beforeLoad)
+		expect(meta.head).toBe(head)
+		expect(m.loaders!.doc).toBe(loader)
+	})
+
+	it('collects path-keyed layouts like _layout files', () => {
+		const m = defineRoutes({
+			routes: [{ path: 'guides/:slug', screen: C('Guide') }],
+			layouts: { guides: C('GuideShell'), '': C('RootShell') },
+		})
+
+		expect(m.layouts.guides.displayName).toBe('GuideShell')
+		expect(m.layouts[''].displayName).toBe('RootShell')
+		expect(layoutChain(m.layouts, 'guides/:slug').map((c) => c.displayName)).toEqual([
+			'GuideShell',
+		])
+	})
+
+	it('warns and skips a non-component screen', () => {
+		const m = defineRoutes([{ path: 'bad', screen: { default: C('B') } as any }])
+		expect(m.screens.bad).toBeUndefined()
+	})
+})
+
+describe('mergeRouteManifests', () => {
+	const files = manifest({
+		'./app/detail.tsrx': { D: C('FileDetail') },
+		'./app/demo/[id].tsrx': { DD: C('FileDemo') },
+		'./app/guides/_layout.tsrx': { L: C('FileLayout') },
+	})
+
+	it('merges screens, metas, and layouts without touching disjoint names', () => {
+		const dynamic = defineRoutes({
+			routes: [{ path: 'guides/:slug', screen: C('Guide') }],
+			layouts: { docs: C('DocsShell') },
+		})
+		const merged = mergeRouteManifests(files, dynamic)
+
+		expect(Object.keys(merged.screens).sort()).toEqual([
+			'demo/:id',
+			'detail',
+			'guides/:slug',
+		])
+		expect(merged.layouts.guides.displayName).toBe('FileLayout')
+		expect(merged.layouts.docs.displayName).toBe('DocsShell')
+		// Sort order is rebuilt — 'demo/:id' still loses to nothing, but a
+		// static dynamic route must outrank a file param route.
+		expect(matchRoute(merged.routes, ['demo', 'x'])!.meta.name).toBe('demo/:id')
+	})
+
+	it('later manifests win same-name routes — meta and config together', () => {
+		const fileLoader = () => 'file'
+		const file = manifest({
+			'./app/detail.tsrx': { D: C('FileDetail'), loader: fileLoader },
+		})
+		const dynamic = defineRoutes([{ path: 'detail', screen: C('DynDetail') }])
+		const merged = mergeRouteManifests(file, dynamic)
+
+		expect(merged.screens.detail.displayName).toBe('DynDetail')
+		const meta = merged.routes.find((r) => r.name === 'detail')!
+		expect(meta.loader).toBeUndefined()
+		expect(merged.loaders!.detail).toBeUndefined()
+	})
+
+	it('file manifest wins when merged after the dynamic one', () => {
+		const dynamic = defineRoutes([{ path: 'detail', screen: C('DynDetail') }])
+		const merged = mergeRouteManifests(dynamic, files)
+
+		expect(merged.screens.detail.displayName).toBe('FileDetail')
+	})
+
+	it('a static dynamic route outranks a file param route in match order', () => {
+		const dynamic = defineRoutes([{ path: 'demo/new', screen: C('NewDemo') }])
+		const merged = mergeRouteManifests(files, dynamic)
+
+		expect(matchRoute(merged.routes, ['demo', 'new'])!.meta.name).toBe('demo/new')
+	})
+})