@keenmate/svelte-spa-router 1.0.1

package/Router.d.ts

@@ -0,0 +1,221 @@
+///<reference types="svelte" />
+
+import {ComponentType, SvelteComponent} from "svelte"
+import {Readable, Writable} from "svelte/store"
+
+/** Dictionary with route details passed to the pre-conditions functions, as well as the `routeLoading` and `conditionsFailed` events */
+export interface RouteDetail {
+	/** Route matched as defined in the route definition (could be a string or a regular expression object) */
+	route: string | RegExp
+
+	/** Location path */
+	location: string
+
+	/** Querystring from the hash */
+	querystring: string
+
+	/** Params matched in the route */
+	params: Record<string, string> | null
+
+	/** Custom data passed by the user */
+	userData?: object
+}
+
+/** Detail object for the `routeLoaded` event */
+export interface RouteDetailLoaded extends RouteDetail {
+	/** Svelte component */
+	component: ComponentType
+
+	/** Name of the Svelte component that was loaded (note: might be minified in production) */
+	name: string
+}
+
+/**
+ * This is a Svelte component loaded asynchronously.
+ * It's meant to be used with the `import()` function, such as `() => import('Foo.svelte')}`
+ */
+export type AsyncSvelteComponent = () => Promise<{ default: ComponentType }>
+
+/**
+ * Route pre-condition function. This is a callback that receives a RouteDetail object as argument containing information on the route that we're trying to load.
+ * The function must return a boolean indicating whether the route can be loaded. If the function returns `false`, the route is not loaded, and no other pre-condition function is executed.
+ *
+ * The pre-condition function can be asynchronous too, returning a boolean asynchronously.
+ *
+ * @param detail Route detail object
+ * @returns If the callback returns a false-y value, it's interpreted as the precondition failed, so it aborts loading the component (and won't process other pre-condition callbacks)
+ */
+export type RoutePrecondition = (detail: RouteDetail) => (boolean | Promise<boolean>)
+
+/** Object returned by the `wrap` method */
+export interface WrappedComponent {
+	/** Component to load (this is always asynchronous) */
+	component: ComponentType
+
+	/** Route pre-conditions to validate */
+	conditions?: RoutePrecondition[]
+
+	/** Optional dictionary of static props */
+	props?: object
+
+	/** Optional user data dictionary */
+	userData?: object
+
+	/**
+	 * Internal flag used by the router to identify wrapped routes
+	 * @internal
+	 */
+	//_sveltesparouter?: boolean
+}
+
+/**
+ * Navigates to a new page programmatically.
+ *
+ * @param location Path to navigate to (must start with `/` or '#/')
+ * @returns Promise that resolves after the page navigation has completed
+ */
+export function push(location: string): Promise<void>
+
+/**
+ * Navigates back in history (equivalent to pressing the browser's back button).
+ *
+ * @returns Promise that resolves after the page navigation has completed
+ */
+export function pop(): Promise<void>
+
+/**
+ * Replaces the current page but without modifying the history stack.
+ *
+ * @param location - Path to navigate to (must start with `/` or '#/')
+ * @returns Promise that resolves after the page navigation has completed
+ */
+export function replace(location: string): Promise<void>
+
+/** Type for the opts parameter of the link action */
+export type LinkActionOpts = {
+	/** A string to use in place of the link's href attribute. Using this allows for updating link's targets reactively. */
+	href?: string
+	/** If true, link is disabled */
+	disabled?: boolean
+}
+
+/** Type for the update function of the link action */
+export type LinkActionUpdateFunc = ((opts?: LinkActionOpts) => void) |
+	((hrefVar?: string) => void)
+
+/** Type for backwards-compatible (typo: Upate) */
+export type LinkActionUpateFunc = LinkActionUpdateFunc
+
+/**
+ * Svelte Action that enables a link element (`<a>`) to use our history management.
+ *
+ * For example:
+ *
+ * ````html
+ * <a href="/books" use:link>View books</a>
+ * ````
+ *
+ * @param node - The target node (automatically set by Svelte). Must be an anchor tag (`<a>`) with a href attribute starting in `/`
+ * @param opts - Dictionary with options for the link
+ * @param hrefVar - A string to use in place of the link's href attribute. Using this allows for updating link's targets reactively. This is a shorthand for opts.href
+ */
+export function link(node: HTMLElement, opts?: LinkActionOpts): { update: LinkActionUpdateFunc }
+export function link(node: HTMLElement, hrefVar?: string): { update: LinkActionUpdateFunc }
+
+/** Full location from the hash: page and querystring */
+interface Location {
+	/** Location (page/view), for example `/book` */
+	location: string
+
+	/** Querystring from the hash, as a string not parsed */
+	querystring?: string
+}
+
+/**
+ * Store to configure whether the router operates on routes hidden behind # or not
+ */
+export const HashRoutingEnabled: Writable<boolean>
+
+/**
+ * Used when hash-based routing is disabled and in normal scenario should be filled with `import.meta.env.BASE_URL` (in case of Vite app)
+ * A '/' prefixed path that will be excluded from URL when dealing with route navigation
+ */
+export const BasePath: Writable<string>
+
+/**
+ * Readable store that returns the current full location (incl. querystring)
+ */
+export const loc: Readable<Location>
+
+/**
+ * Readable store that returns the current location
+ */
+export const location: Readable<string>
+
+/**
+ * Readable store that returns the current querystring
+ */
+export const querystring: Readable<string | undefined>
+
+/**
+ * Readable store that returns the current list of params
+ */
+export const params: Readable<Record<string, string> | undefined>
+// Note: the above is implemented as writable but exported as readable because consumers should not modify the value
+
+/** List of routes */
+export type RouteDefinition = Record<string, ComponentType | WrappedComponent> |
+	Map<string | RegExp, ComponentType | WrappedComponent>
+
+/** Generic interface for events from the router */
+interface RouterEvent<T> {
+	detail: T
+}
+
+/** Event type for conditionsFailed */
+export type ConditionsFailedEvent = RouterEvent<RouteDetail>
+
+/** Event type for routeLoading */
+export type RouteLoadingEvent = RouterEvent<RouteDetail>
+
+/** Event type for routeLoaded */
+export type RouteLoadedEvent = RouterEvent<RouteDetailLoaded>
+
+/**
+ * Router component
+ */
+export default class Router extends SvelteComponent {
+	// Props
+	$$prop_def: {
+		/**
+		 * Dictionary of all routes, in the format `'/path': component`.
+		 *
+		 * For example:
+		 * ````js
+		 * import HomeRoute from './routes/HomeRoute.svelte'
+		 * import BooksRoute from './routes/BooksRoute.svelte'
+		 * import NotFoundRoute from './routes/NotFoundRoute.svelte'
+		 * routes = {
+		 *     '/': HomeRoute,
+		 *     '/books': BooksRoute,
+		 *     '*': NotFoundRoute
+		 * }
+		 * ````
+		 */
+		routes: RouteDefinition,
+		/**
+		 * Optional prefix for the routes in this router. This is useful for example in the case of nested routers.
+		 */
+		prefix?: string | RegExp,
+		/**
+		 * If set to true, the router will restore scroll positions on back navigation
+		 * and scroll to top on forward navigation.
+		 */
+		restoreScrollState?: boolean
+	}
+
+	$on(event: "routeEvent", callback: (event: CustomEvent) => void): () => void
+	$on(event: "conditionsFailed", callback: (event: ConditionsFailedEvent) => void): () => void
+	$on(event: "routeLoading", callback: (event: RouteLoadingEvent) => void): () => void
+	$on(event: "routeLoaded", callback: (event: RouteLoadedEvent) => void): () => void
+}