navgo 6.0.2 → 6.0.4

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

@@ -7,6 +7,10 @@ export * as v from 'valibot'
  */
 export type RawParam = string | null | undefined
 export type Params = Record<string, any>
+export type SearchParams = Record<string, unknown>
+export type SearchParamsStore = import('svelte/store').Writable<SearchParams> & {
+	toString(): string
+}
 
 export type ParamSchema = import('valibot').BaseSchema<unknown, unknown, any>
 export type ParamRule = ParamSchema | { schema?: ParamSchema; coercer?: (value: RawParam) => any }
@@ -83,6 +87,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 +97,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 +125,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 +150,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 +175,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,20 +237,21 @@ 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>[]
-		search_params: Record<string, unknown>
+		layouts: LayoutsMap<T>
+		search_params: SearchParams
 	}>
 	/** Last completed navigation object. */
 	nav: Navigation | null
 	/** Writable store indicating active navigation. */
 	readonly is_navigating: import('svelte/store').Writable<boolean>
 	/** Writable store of validated search params for the current route. */
-	readonly search_params: import('svelte/store').Writable<Record<string, unknown>>
+	readonly search_params: SearchParamsStore
 	/** Invalidate cache entries by canonical keys (URLs) or tags. */
 	invalidate(keys_or_tags: string | string[]): Promise<void>
 }

package/index.js

@@ -3,7 +3,9 @@ import { debounce } from 'es-toolkit/function'
 import { isPromise } from 'es-toolkit/predicate'
 import * as v from 'valibot'
 import {
+	build_search_string,
 	build_search_url,
+	create_search_store,
 	merge_search_opts,
 	normalize_path,
 	read_search,
@@ -49,8 +51,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,12 +90,13 @@ export default class Navgo {
 		route: null,
 		params: {},
 		matches: [],
+		layouts: Object.create(null),
 		search_params: {},
 	})
 	/** @type {Navigation|null} */
 	nav = null
 	is_navigating = writable(false)
-	search_params = writable({})
+	search_params = create_search_store()
 
 	//
 	// Event listeners
@@ -414,9 +424,23 @@ export default class Navgo {
 			this.#search_opts.debounce > 0
 				? debounce(v => this.#commit_search(v), this.#search_opts.debounce)
 				: null
+		this.search_params.set_stringifier(v => this.#stringify_search(v))
 		this.#set_search_store(search?.search_params ?? {})
 	}
 
+	#stringify_search(values) {
+		if (!this.#search_schema) return ''
+		const cur = this.#current.url || new URL(location.href)
+		return build_search_string(
+			cur,
+			values,
+			this.#search_keys,
+			this.#search_defaults,
+			this.#search_opts,
+			isEqual,
+		)
+	}
+
 	/* Read + validate search params from URL. */
 	#sync_search_from_url(url) {
 		if (!this.#search_schema) return this.#set_search_store({})
@@ -632,10 +656,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 +702,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 +721,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 +779,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 +813,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 +890,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 +908,7 @@ export default class Navgo {
 							params: prev.params || {},
 							route: prev.route,
 							matches: prev.matches || [],
+							layouts: prev.layouts || Object.create(null),
 						}
 					: null,
 				to: {
@@ -877,6 +916,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 +1187,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 +1208,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 +1225,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.4",
 	"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,15 +173,16 @@ 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: SearchParams }>`
   - Readonly property that holds the current snapshot.
   - Subscribe to react to changes; Navgo updates it on every URL change.
 - `router.is_navigating` -- `Writable<boolean>`
   - `true` while a navigation is in flight (between start and completion/cancel).
-- `router.search_params` -- `Writable<Record<string, unknown>>`
+- `router.search_params` -- `Writable<SearchParams> & { toString(): string }`
   - Writable store of validated search params for the **current** route.
   - If the current route defines a `search_schema`, this store is kept in sync with the URL.
   - Writing to it updates the URL search string (optionally debounced).
+  - The store object has a custom `toString()` that returns the canonical query string (without the leading `?`) for the current route, using `URLSearchParams` encoding.
 
 Example:
 
@@ -255,6 +258,7 @@ Notes:
 
 - Writes are **shallow** (URL changes via `replace_state` / `push_state`), so loaders are not re-run automatically.
 - If you want a full navigation, call `router.goto(...)` with a new URL.
+- You can serialize the current managed query with `router.search_params.toString()`.
 
 ### Route Hooks
 
@@ -315,8 +319,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 +328,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 +337,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 +567,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()`.

package/utils.js

@@ -1,3 +1,4 @@
+import { writable } from 'svelte/store'
 import * as v from 'valibot'
 
 export function normalize_path(value) {
@@ -125,7 +126,7 @@ function safe_json(value) {
 	}
 }
 
-export function build_search_url(cur, values, keys, defaults, opts, same_value) {
+export function build_search_string(cur, values, keys, defaults, opts, same_value) {
 	let sp = new URLSearchParams(cur.search)
 	const as = opts?.array_style
 	for (const k of keys) {
@@ -159,8 +160,34 @@ export function build_search_url(cur, values, keys, defaults, opts, same_value)
 	if (opts?.sort) {
 		sp = new URLSearchParams([...sp.entries()].sort(([a], [b]) => a.localeCompare(b)))
 	}
+	return sp.toString()
+}
+
+export function build_search_url(cur, values, keys, defaults, opts, same_value) {
 	const next = new URL(cur.href)
-	const s = sp.toString()
+	const s = build_search_string(cur, values, keys, defaults, opts, same_value)
 	next.search = s ? `?${s}` : ''
 	return next.href === cur.href ? null : next
 }
+
+export function create_search_store(stringify = () => '') {
+	let current = {}
+	const store = writable(current)
+	const api = {
+		subscribe: store.subscribe,
+		set(value) {
+			current = value && typeof value === 'object' ? value : {}
+			store.set(current)
+		},
+		update(fn) {
+			api.set(fn(current))
+		},
+		toString() {
+			return stringify(current)
+		},
+		set_stringifier(fn) {
+			stringify = fn || (() => '')
+		},
+	}
+	return api
+}