navgo 6.0.2 → 6.0.3

package/changelog.md

@@ -3,6 +3,12 @@
 ## v6
 
 - add route groups for nested layouts/shared loaders; expose ordered `matches` (layouts → route) on `nav.to.matches` and `router.route`
+- add optional route group `id`s plus keyed `layouts` lookups on navigation targets, `match()`, and `router.route` for direct access to shared layout/group data
+  - migration:
+    - before: `const app_data = nav.to?.matches?.find(m => m.type === 'layout')?.data`
+    - after: `const app_data = nav.to?.layouts?.app?.data`
+  - docs/typed surfaces now describe `match()` as returning `{ route, params, matches, layouts }` and `window.navgo.route` as including `layouts`
+  - covered on direct `match()`, completed navigations, `popstate`, and preload-reused navigations
 - run group loaders (and group `before_route_leave`) for matched child routes; preload caches the full loader chain and `goto` reuses it
 - use `param_rules` for per-param validation + coercion (superseding `param_validators`, which has been removed)
   - example:

package/index.d.ts

@@ -83,6 +83,8 @@ export interface LoaderContext {
 export interface Match<T = unknown> {
 	/** Matched layout/group wrapper or the final route tuple. */
 	type: 'layout' | 'route'
+	/** Present when `type === 'layout'` and the route group declared an `id`. */
+	id?: string
 	/** Present when `type === 'layout'`. */
 	layout?: any
 	/** Present when `type === 'route'`. */
@@ -91,7 +93,17 @@ export interface Match<T = unknown> {
 	data?: unknown
 }
 
+export interface LayoutMatch<T = unknown> extends Match<T> {
+	type: 'layout'
+	id: string
+}
+
+/** Keyed lookup into matched layout/group wrappers. Values are the same objects as in `matches`. */
+export type LayoutsMap<T = unknown> = Record<string, LayoutMatch<T>>
+
 export interface RouteGroup<T = unknown> {
+	/** Optional stable key for direct access via `layouts[id]`. Must be unique across groups. */
+	id?: string
 	/** Optional layout component/module (router does not render; it just forwards this). */
 	layout?: any
 	/** Load data for this layout group. Return a LoadPlan (object) or a Promise for arbitrary data. */
@@ -109,6 +121,7 @@ export type RouteEntry<T = unknown> = RouteTuple<T> | RouteGroup<T>
 
 export interface PreloadBundle<T = unknown> {
 	matches: Match<T>[]
+	layouts?: LayoutsMap<T>
 	data?: unknown
 }
 
@@ -133,6 +146,8 @@ export interface NavigationTarget<T = unknown> {
 	route: RouteTuple<T> | null
 	/** Ordered matches for nested layouts and the final route (outer → inner). */
 	matches?: Match<T>[]
+	/** Keyed lookup into matched layout/group wrappers by `RouteGroup.id`. */
+	layouts?: LayoutsMap<T>
 	/** Optional data from route loader when available. */
 	data?: unknown
 }
@@ -156,6 +171,7 @@ export interface MatchResult<T = unknown> {
 	route: RouteTuple<T>
 	params: Params
 	matches: Match<T>[]
+	layouts: LayoutsMap<T>
 }
 
 // For convenience in docs/types, alias the class instance type
@@ -217,12 +233,13 @@ export default class Navgo<T = unknown> {
 	init(): Promise<void>
 	/** Remove listeners installed by `init()`. */
 	destroy(): void
-	/** Writable store with current { url, route, params, matches, search_params }. */
+	/** Writable store with current { url, route, params, matches, layouts, search_params }. */
 	readonly route: import('svelte/store').Writable<{
 		url: URL
 		route: RouteTuple<T> | null
 		params: Params
 		matches: Match<T>[]
+		layouts: LayoutsMap<T>
 		search_params: Record<string, unknown>
 	}>
 	/** Last completed navigation object. */

package/index.js

@@ -49,8 +49,15 @@ export default class Navgo {
 	#base_rgx = /^\/+/
 	/** @type {Map<string, { promise?: Promise<PreloadBundle>, data?: PreloadBundle }>} */
 	#preloads = new Map()
-	/** @type {{ url: URL|null, route: RouteTuple|null, params: Params, matches: Match[], search_params: Record<string, unknown> }} */
-	#current = { url: null, route: null, params: {}, matches: [], search_params: {} }
+	/** @type {{ url: URL|null, route: RouteTuple|null, params: Params, matches: Match[], layouts: Record<string, Match>, search_params: Record<string, unknown> }} */
+	#current = {
+		url: null,
+		route: null,
+		params: {},
+		matches: [],
+		layouts: Object.create(null),
+		search_params: {},
+	}
 	/** @type {number} */
 	#route_idx = 0
 	/** @type {boolean} */
@@ -81,6 +88,7 @@ export default class Navgo {
 		route: null,
 		params: {},
 		matches: [],
+		layouts: Object.create(null),
 		search_params: {},
 	})
 	/** @type {Navigation|null} */
@@ -632,10 +640,17 @@ export default class Navgo {
 		}
 	}
 
+	#build_layouts(matches) {
+		const out = Object.create(null)
+		for (const m of matches || []) if (m.type === 'layout' && m.id) out[m.id] = m
+		return out
+	}
+
 	#build_matches(route, stack) {
 		const out = []
 		for (const g of stack || []) {
 			const obj = { type: 'layout', layout: g.layout }
+			if (g.id) obj.id = g.id
 			Object.defineProperty(obj, '__entry', { value: g })
 			out.push(obj)
 		}
@@ -671,6 +686,7 @@ export default class Navgo {
 		for (let i = 0; i < matches.length; i++) matches[i].data = datas[i]
 		return {
 			matches,
+			layouts: this.#build_layouts(matches),
 			data: datas[datas.length - 1],
 			search: { schema, opts, defaults, search_params },
 		}
@@ -689,6 +705,7 @@ export default class Navgo {
 							params: this.#current.params || {},
 							route: this.#current.route,
 							matches: this.#current.matches || [],
+							layouts: this.#current.layouts || Object.create(null),
 						}
 					: null
 		return {
@@ -746,7 +763,7 @@ export default class Navgo {
 
 			let nav = this.#make_nav({
 				type: nav_type,
-				to: { url, params: {}, route: null, matches: [] },
+				to: { url, params: {}, route: null, matches: [], layouts: Object.create(null) },
 				event: ev_param,
 			})
 			ℹ('[🧭 goto]', 'start', {
@@ -780,8 +797,9 @@ export default class Navgo {
 						params: hit.params || {},
 						route: hit.route || null,
 						matches: hit.matches || [],
+						layouts: hit.layouts || this.#build_layouts(hit.matches || []),
 					}
-				: { url, params: {}, route: null, matches: [] }
+				: { url, params: {}, route: null, matches: [], layouts: Object.create(null) }
 			if (match_error) nav.to.data = { __error: match_error }
 
 			// before_navigate (skip initial)
@@ -856,6 +874,10 @@ export default class Navgo {
 				route: match_error ? null : hit?.route || null,
 				params: match_error ? {} : hit?.params || {},
 				matches,
+				layouts:
+					hit && !match_error
+						? bundle?.layouts || this.#build_layouts(matches)
+						: Object.create(null),
 				search_params: {},
 			}
 
@@ -870,6 +892,7 @@ export default class Navgo {
 							params: prev.params || {},
 							route: prev.route,
 							matches: prev.matches || [],
+							layouts: prev.layouts || Object.create(null),
 						}
 					: null,
 				to: {
@@ -877,6 +900,7 @@ export default class Navgo {
 					params: match_error ? {} : hit?.params || {},
 					route: match_error ? null : hit?.route || null,
 					matches,
+					layouts: this.#current.layouts || Object.create(null),
 					data,
 				},
 				event: ev_param,
@@ -1147,10 +1171,12 @@ export default class Navgo {
 			}
 
 			ℹ('[🧭 match]', 'hit', { pattern: obj.data?.[0], params })
+			const matches = this.#build_matches(obj.data, obj.stack)
 			return {
 				route: obj.data || null,
 				params,
-				matches: this.#build_matches(obj.data, obj.stack),
+				matches,
+				layouts: this.#build_layouts(matches),
 			}
 		}
 		ℹ('[🧭 match]', 'miss', { url: url_raw })
@@ -1166,6 +1192,8 @@ export default class Navgo {
 		this.#base_rgx =
 			this.#base == '/' ? /^\/+/ : new RegExp('^\\' + this.#base + '(?=\\/|$)\\/?', 'i')
 
+		const group_ids = new Map()
+
 		function compile_routes(entries, stack = []) {
 			const out = []
 			for (const e of entries || []) {
@@ -1181,6 +1209,14 @@ export default class Navgo {
 					continue
 				}
 				if (e && typeof e === 'object' && Array.isArray(e.routes)) {
+					if (e.id != null) {
+						if (typeof e.id !== 'string' || !e.id) {
+							throw new Error('Route group id must be a non-empty string')
+						}
+						if (group_ids.has(e.id))
+							throw new Error(`Duplicate route group id "${e.id}"`)
+						group_ids.set(e.id, e)
+					}
 					out.push(...compile_routes(e.routes, stack.concat(e)))
 					continue
 				}

package/llms.txt

@@ -6,7 +6,7 @@
 - `goto()` and `preload()` are safe to call without `await` from events (no unhandled rejections); errors surface via `nav.to.data.__error` (or preload bundle `data.__error`)
 - `router.init()` attaches the router instance to `window.navgo` by default
 - stores:
-  - `window.navgo.route`: `{ url, route, params, matches, search_params }`
+  - `window.navgo.route`: `{ url, route, params, matches, layouts, search_params }`
   - `window.navgo.is_navigating`: boolean
 
 ## Setup (App Wiring)
@@ -52,6 +52,7 @@
 - Handle 404 / loader errors:
   - `const err = nav.to?.data?.__error; if (err?.status === 404) show_404 = true`
 - Shared layout data:
-  - read `nav.to.matches` outer → inner; layouts are `m.type === 'layout'`, route leaf is `m.type === 'route'`
+  - use `nav.to.layouts?.id?.data` or `$route.layouts?.id?.data` for direct access to matched group data
+  - `nav.to.matches` remains the ordered outer → inner structure; layouts are `m.type === 'layout'`, route leaf is `m.type === 'route'`
 - Stable scroll panes:
   - set `id="pane"` or `data-scroll-id="pane"` on scroll containers to get popstate restoration

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "6.0.2",
+	"version": "6.0.3",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"

package/readme.md

@@ -114,6 +114,7 @@ Each route group is an object:
 
 ```js
 {
+  id?: string,
   layout?: any,
   loader?: (ctx) => LoadPlan | Promise<unknown>,
   before_route_leave?: (nav) => void,
@@ -121,6 +122,7 @@ Each route group is an object:
 }
 ```
 
+- `id` enables direct keyed access via `nav.to.layouts[id]` / `$route.layouts[id]`. IDs must be unique across route groups.
 - `layout` is forwarded into `nav.to.matches` (the router does not render anything).
 - `loader` runs for every matched child route in the group.
 - `before_route_leave` runs when leaving a matched route within the group.
@@ -171,7 +173,7 @@ Important: Navgo only processes routes that match your `base` path.
 
 ### Instance stores
 
-- `router.route` -- `Writable<{ url: URL; route: RouteTuple|null; params: Params; matches: Match[]; search_params: Record<string, unknown> }>`
+- `router.route` -- `Writable<{ url: URL; route: RouteTuple|null; params: Params; matches: Match[]; layouts: Record<string, Match>; search_params: Record<string, unknown> }>`
   - Readonly property that holds the current snapshot.
   - Subscribe to react to changes; Navgo updates it on every URL change.
 - `router.is_navigating` -- `Writable<boolean>`
@@ -315,8 +317,8 @@ The `Navigation` object contains:
 ```ts
 {
   type: 'link' | 'goto' | 'popstate' | 'leave',
-  from: { url, params, route, matches } | null,
-  to:   { url, params, route, matches, data } | null,
+  from: { url, params, route, matches, layouts } | null,
+  to:   { url, params, route, matches, layouts, data } | null,
   will_unload: boolean,
   cancelled: boolean,
   event?: Event,
@@ -324,7 +326,7 @@ The `Navigation` object contains:
 }
 ```
 
-`nav.to.matches` is ordered **outer → inner** and contains both layouts and the final route:
+`nav.to.matches` is ordered **outer → inner** and remains the canonical structure:
 
 ```js
 for (const m of nav.to?.matches || []) {
@@ -333,6 +335,13 @@ for (const m of nav.to?.matches || []) {
 }
 ```
 
+If a matched route group declares an `id`, Navgo also exposes a keyed lookup that points at the same match object:
+
+```js
+const session = nav.to?.layouts?.app?.data
+const admin_layout = $route.layouts?.admin
+```
+
 #### Order & cancellation:
 
 - Router calls `before_route_leave` on the current route (leave).
@@ -556,7 +565,7 @@ scroll flow
 ### Method-by-Method Semantics
 
 - `format(uri)` -- normalizes a path relative to `base`. Returns `false` when `uri` is outside of `base`.
-- `match(uri)` -- returns a Promise of `{ route, params } | null` using string/RegExp patterns and `param_rules` (Valibot schemas). Awaits an async `validate(params)` if provided.
+- `match(uri)` -- returns a Promise of `{ route, params, matches, layouts } | null` using string/RegExp patterns and `param_rules` (Valibot schemas). Awaits an async `validate(params)` if provided.
 - `goto(uri, { replace? })` -- fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loader, pushes/replaces, and completes via `after_navigate`.
 - `init()` -- wires global listeners (`popstate`, `pushstate`, `replacestate`, click) and optional hover/tap preloading; immediately processes the current location.
 - `destroy()` -- removes listeners added by `init()`.