crelte 0.1.1 → 0.1.3

package/src/loadData/Globals.ts

@@ -25,13 +25,28 @@ export default class Globals {
 		this.prevSiteId = null;
 	}
 
-	get(name: string): Global<any> | null {
+	/**
+	 * returns a store which contains a globalSet
+	 *
+	 * ## Note
+	 * This only works in loadData, in loadGlobalData this will
+	 * always return null. In that context you should use
+	 * `.getGlobalAsync`
+	 */
+	get<T extends GlobalData>(name: string): Global<T> | null {
 		return this.entries.get(name) ?? null;
 	}
 
-	// call this only in loadGlobalData when by default the global
-	// is not available
-	getAsync(name: string): Promise<Global<any> | null> | Global<any> | null {
+	/**
+	 * Get a store which contains a globalSet and wait until it is loaded
+	 *
+	 * ## Note
+	 * This is only useful in loadGlobalData in all other cases
+	 * you can use `.getGlobal` which does return a Promise
+	 */
+	getAsync<T extends GlobalData>(
+		name: string,
+	): Promise<Global<T> | null> | Global<T> | null {
 		if (this.loaded) return this.get(name);
 
 		let waiter = this.waiters.get(name);
@@ -45,15 +60,15 @@ export default class Globals {
 		});
 	}
 
-	// hidden
+	/** @hidden */
 	_wasLoaded(): boolean {
 		return this.loaded;
 	}
 
-	// hidden
 	// data is the data from the global graphql
 	// so it contains some keys and data which should be parsed
 	// and created a store for each key
+	/** @hidden */
 	_setData(siteId: number, data: any) {
 		const wasLoaded = this.loaded;
 		this.loaded = true;
@@ -70,6 +85,7 @@ export default class Globals {
 		}
 	}
 
+	/** @hidden */
 	_globalsBySite(siteId: number): Map<string, any> {
 		const map = new Map();
 
@@ -80,6 +96,7 @@ export default class Globals {
 		return map;
 	}
 
+	/** @hidden */
 	_updateSiteId(siteId: number) {
 		// todo we should only trigger
 		if (this.prevSiteId === siteId) return;
@@ -88,10 +105,19 @@ export default class Globals {
 	}
 }
 
+/**
+ * A globalSet Data
+ *
+ * Each global query should contain the siteId
+ */
 export interface GlobalData {
 	siteId?: number;
+	[key: string]: any;
 }
 
+/**
+ * A globalSet store
+ */
 export class Global<T extends GlobalData> {
 	private inner: Writable<T>;
 	/// if languages is null this means we always have the same data
@@ -129,11 +155,20 @@ export class Global<T extends GlobalData> {
 		return this.inner.subscribe(fn);
 	}
 
+	/**
+	 * The current value
+	 */
 	get(): T {
 		return this.inner.get();
 	}
 
-	/// if you pass a siteId which comes from craft then you will never receive null
+	/**
+	 * Get the value based on the siteId
+	 *
+	 * ## Note
+	 * If you pass a siteId which comes from craft
+	 * you will never receive null
+	 */
 	bySiteId(siteId: number): T | null {
 		if (this.languages)
 			return this.languages.find(d => d.siteId === siteId) ?? null;
@@ -141,6 +176,7 @@ export class Global<T extends GlobalData> {
 		return this.inner.get();
 	}
 
+	/** @hidden */
 	_updateSiteId(siteId: number) {
 		if (!this.languages) return;
 

package/src/loadData/index.ts

@@ -1,22 +1,85 @@
-/**
- *
- */
-
-import type CrelteRouted from '../CrelteRouted.js';
+import CrelteRequest from '../CrelteRequest.js';
 import { isGraphQlQuery, type GraphQlQuery } from '../graphql/GraphQl.js';
 import type Globals from './Globals.js';
 import type { Global } from './Globals.js';
 
 export type { Globals, Global };
 
+/**
+ * Load data function
+ *
+ * There are three main ways `loadData` can be defined:
+ *
+ * ## Object
+ * This is the most common way loadData will be used.
+ * Each property should be a loadData type, each one is called in parallel.
+ * And will be available to your component with the same name.
+ * ```
+ * export const loadData = {
+ *
+ * import entriesQuery from '@/queries/entries.graphql';
+ * import { loadData as headerLoadData } from '@/layout/header.svelte';
+ *
+ * export const loadData = {
+ *     entries: entriesQuery,
+ *     header: headerLoadData
+ * };
+ * ```
+ *
+ * ## GraphQl
+ * You can just export a graphql query as a loadData type.
+ * This will export all queries from the graphql file as properties.
+ * ```
+ * import blogsQuery from '@/queries/blogs.graphql';
+ *
+ * export const loadData = blogsQuery;
+ *
+ * // or another option
+ * import { gql } from '@craft-svelte/core/graphql';
+ *
+ * export const loadData = gql`query {
+ *   blogs: entries(section: "blogs") {
+ *     title
+ *     url
+ *  }
+ * }`;
+ * ```
+ *
+ * ## Function
+ * Using a function gives you the most flexibility but also is the
+ * most cumbersome.
+ *
+ * ```
+ * import articlesQuery from '@/queries/articles.graphql';
+ *
+ * export async function loadData(cr, entry) {
+ *     return await cr.query(articlesQuery, {
+ *         category: entry.category
+ *     });
+ * }
+ *
+ * // or
+ * export const loadData = (cr, entry) => cr.query(articlesQuery, {
+ *     category: entry.category
+ * });
+ *
+ * // or if you're in the context of an object
+ * export const loadData = {
+ *     articles: (cr, entry) => cr.query(articlesQuery, {
+ *         category: entry.category
+ *     })
+ * }
+ * ```
+ */
+
 export type LoadData<T> =
-	| ((cr: CrelteRouted, ...args: any[]) => Promise<T>)
+	| ((cr: CrelteRequest, ...args: any[]) => Promise<T>)
 	| GraphQlQuery
 	| T;
 
 export async function callLoadData(
 	ld: LoadData<unknown>,
-	cr: CrelteRouted,
+	cr: CrelteRequest,
 	...args: any[]
 ): Promise<unknown> {
 	// either we have a function
@@ -49,15 +112,15 @@ export async function callLoadData(
  * ## Example
  * ```
  * export const loadData = mergeLoadData(
- * 		{
- * 			filter: (cr) => cr.route.search.get('filter'),
- * 		},
- * 		(cr) => cr.query(myQuery, { siteId: cr.site.id })
- * )
+ *     {
+ * 	        filter: (cr) => cr.route.search.get('filter'),
+ *     },
+ *     (cr) => cr.query(myQuery, { siteId: cr.site.id })
+ * );
  * ```
  */
 export function mergeLoadData(...lds: LoadData<object>[]): LoadData<object> {
-	return async (cr: CrelteRouted, ...args: any[]) => {
+	return async (cr: CrelteRequest, ...args: any[]) => {
 		const datas = await Promise.all(
 			lds.map(ld => callLoadData(ld, cr, ...args) as Promise<object>),
 		);

package/src/plugins/Events.ts

@@ -1,4 +1,4 @@
-import { CrelteRouted } from '../index.js';
+import { CrelteRequest } from '../index.js';
 
 export default class Events {
 	inner: Map<string, Set<any>>;
@@ -7,19 +7,21 @@ export default class Events {
 		this.inner = new Map();
 	}
 
-	/*
+	/**
 	 * Listens for an event.
+	 *
+	 * @returns a function to remove the listener
 	 */
 	// override this function to add your own function signatures
 	on(
 		ev: 'loadGlobalData',
-		fn: (cr: CrelteRouted) => Promise<any>,
+		fn: (cr: CrelteRequest) => Promise<any>,
 	): () => void;
 	on(
 		ev: 'loadData',
-		fn: (cr: CrelteRouted, entry: any, data: any) => Promise<any>,
+		fn: (cr: CrelteRequest, entry: any) => Promise<any>,
 	): () => void;
-	on(ev: 'beforeRender', fn: (cr: CrelteRouted) => void): () => void;
+	on(ev: 'beforeRender', fn: (cr: CrelteRequest) => void): () => void;
 	on(ev: string, fn: (...args: any[]) => any): () => void {
 		let set = this.inner.get(ev);
 		if (!set) {
@@ -34,6 +36,9 @@ export default class Events {
 		};
 	}
 
+	/**
+	 * Remove a listener
+	 */
 	remove(ev: string, fn: any) {
 		const set = this.inner.get(ev);
 		if (!set) return;
@@ -41,6 +46,12 @@ export default class Events {
 		set.delete(fn);
 	}
 
+	/**
+	 * Trigger an event
+	 */
+	trigger(ev: 'loadGlobalData', cr: CrelteRequest): Promise<any>[];
+	trigger(ev: 'loadData', cr: CrelteRequest, entry: any): Promise<any>[];
+	trigger(ev: 'beforeRender', cr: CrelteRequest): void[];
 	trigger(ev: string, ...args: any[]): any[] {
 		const set = this.inner.get(ev);
 		if (!set) return [];

package/src/plugins/Plugins.ts

@@ -1,11 +1,32 @@
-import Crelte from '../Crelte.js';
+import CrelteCore from '../Crelte.js';
 
+/**
+ * A plugin
+ */
 export interface Plugin {
 	name: string;
 }
 
-export type PluginCreator = (crelte: Crelte) => Plugin;
+/**
+ * A plugin create function
+ *
+ * Each plugin needs to export a createPluginname function which will be called
+ * by crelte to create the plugin. If youre plugin has options you can create
+ * a configurePluginname function which will be called by youre user and should
+ * return a createPlugin function.
+ *
+ * ## Example App.svelte in module="context"
+ * ```
+ * import { createPlugin, configurePlugin } from 'some-plugin';
+ *
+ * export plugins = [createPlugin, configurePlugin({ enableFeature: true })];
+ * ```
+ */
+export type PluginCreator = (crelte: CrelteCore) => Plugin;
 
+/**
+ * A plugin manager
+ */
 export default class Plugins {
 	plugins: Map<string, Plugin>;
 
@@ -13,6 +34,11 @@ export default class Plugins {
 		this.plugins = new Map();
 	}
 
+	/**
+	 * @hidden
+	 *
+	 * Plugins should be added via App.svelte plugins export
+	 */
 	add(plugin: Plugin) {
 		this.plugins.set(plugin.name, plugin);
 	}

package/src/routing/History.ts

@@ -3,6 +3,7 @@ export default interface History {
 	replaceState(data: any, url?: string): void;
 	pushState(data: any, url: string): void;
 	open(url: string): void;
+	back(): void;
 }
 
 export class ClientHistory implements History {
@@ -21,6 +22,10 @@ export class ClientHistory implements History {
 	open(url: string): void {
 		window.location.href = url;
 	}
+
+	back(): void {
+		window.history.back();
+	}
 }
 
 export class ServerHistory implements History {
@@ -49,4 +54,8 @@ export class ServerHistory implements History {
 	open(url: string): void {
 		this.url = url;
 	}
+
+	back(): void {
+		throw new Error('Cannot go back on the server');
+	}
 }

package/src/routing/InnerRouter.ts

@@ -1,6 +1,8 @@
-import Route from './Route.js';
 import Site, { SiteFromGraphQl } from './Site.js';
-import History, { ClientHistory, ServerHistory } from './History.js';
+import History from './History.js';
+import { ClientHistory, ServerHistory } from './History.js';
+import Request, { isRequest } from './Request.js';
+import Route from './Route.js';
 
 export type InnerRouterOpts = {
 	preloadOnMouseOver: boolean;
@@ -19,8 +21,8 @@ export default class InnerRouter {
 	 * @param changeHistory returns a function you need to call when you are ready to
 	 update the window history (note do not call this after another onRoute call was made)
 	 */
-	onRoute: (route: Route, site: Site, changeHistory: () => void) => void;
-	onPreload: (route: Route, site: Site) => void;
+	onRoute: (route: Request, site: Site, changeHistory: () => void) => void;
+	onPreload: (route: Request, site: Site) => void;
 
 	private scrollDebounceTimeout: any | null;
 
@@ -56,7 +58,7 @@ export default class InnerRouter {
 		this.listen();
 
 		// let's first try to load from the state
-		const route = this.targetToRoute(window.location.href);
+		const route = this.targetToRequest(window.location.href);
 		route._fillFromState(window.history.state);
 
 		route.origin = 'init';
@@ -139,7 +141,7 @@ export default class InnerRouter {
 	 * @param target
 	 * @return Returns null if the url does not match our host (the protocol get's ignored)
 	 */
-	targetToRoute(target: string | URL | Route): Route {
+	targetToRequest(target: string | URL | Route | Request): Request {
 		if (typeof target === 'string') {
 			if (target.startsWith('/')) {
 				const site = this.site;
@@ -150,7 +152,11 @@ export default class InnerRouter {
 		}
 
 		if (target instanceof URL) {
-			return this.routeFromUrl(target);
+			target = this.routeFromUrl(target);
+		}
+
+		if (!isRequest(target)) {
+			return Request.fromRoute(target);
 		}
 
 		return target;
@@ -269,7 +275,7 @@ export default class InnerRouter {
 		window.addEventListener('popstate', async e => {
 			if (!('route' in e.state)) return;
 
-			const route = this.targetToRoute(window.location.href);
+			const route = this.targetToRequest(window.location.href);
 			route._fillFromState(e.state);
 			route.origin = 'pop';
 
@@ -288,12 +294,12 @@ export default class InnerRouter {
 	 * @param route a route object or an url or uri, never input the same route object again
 	 * @param pushState if true pushed the state to the window.history
 	 */
-	open(target: string | URL | Route, pushState: boolean = true) {
-		const route = this.targetToRoute(target);
+	open(target: string | URL | Route | Request, pushState: boolean = true) {
+		const req = this.targetToRequest(target);
 
 		const current = this.route;
 		if (current) {
-			// if the scrollY will still be updated we clear the timeout
+			// if the scrollY would still be updated we clear the timeout
 			// since we should have the latest scrollY
 			if (this.scrollDebounceTimeout) {
 				clearTimeout(this.scrollDebounceTimeout);
@@ -311,20 +317,21 @@ export default class InnerRouter {
 		// if the domain of the current site is different than the domain of the
 		// new site we need to do a window.location.href call
 		if (
-			(current && current.url.origin !== route.url.origin) ||
+			(current && current.url.origin !== req.url.origin) ||
+			// @ts-ignore
 			import.meta.env.SSR
 		) {
-			this.history.open(route.url.href);
+			this.history.open(req.url.href);
 			return;
 		}
 
 		if (pushState) {
-			route.index = (current?.index ?? 0) + 1;
-			this.onRoute(route, route.site ?? this.site, () => {
-				this.pushState(route);
+			req.index = (current?.index ?? 0) + 1;
+			this.onRoute(req, req.site ?? this.site, () => {
+				this.pushState(req.toRoute());
 			});
 		} else {
-			this.setRoute(route);
+			this.setRoute(req);
 		}
 	}
 
@@ -334,13 +341,13 @@ export default class InnerRouter {
 	 * Will trigger an onRoute event but will not store any scroll progress
 	 * or modify the history
 	 *
-	 * @param route
+	 * @param req
 	 */
-	setRoute(route: Route) {
-		this.route = route;
-		if (route.site) this.site = route.site;
+	setRoute(req: Request) {
+		this.route = req.toRoute();
+		if (req.site) this.site = req.site;
 
-		this.onRoute(route, this.site, () => {});
+		this.onRoute(req, this.site, () => {});
 	}
 
 	/**
@@ -389,26 +396,29 @@ export default class InnerRouter {
 	 *
 	 * @param url
 	 */
-	preload(target: string | URL | Route) {
-		const route = this.targetToRoute(target);
+	preload(target: string | URL | Route | Request) {
+		const req = this.targetToRequest(target);
 
+		// todo, don't think this makes any sense
 		// if the domain of the current site is different than the domain of the
 		// new site id does not make sense to preload
-		if (this.site.url.origin !== route.url.origin) {
+		if (this.site.url.origin !== req.url.origin) {
 			return;
 		}
 
 		const current = this.route;
-		const site = route.site ?? this.site;
+		const site = req.site ?? this.site;
 
 		// if the origin matches, the route will be able to be load
 		// so let's preload it
-		if (current && current.url.origin === route.url.origin) {
-			this.onPreload(route, site);
+		if (current && current.url.origin === req.url.origin) {
+			this.onPreload(req, site);
 		}
 	}
 
-	domReady(route: Route) {
+	domReady(req: Request) {
+		if (req.disableScroll) return;
+
 		// scroll to target
 		let scrollTo:
 			| { top: number; behavior: ScrollBehavior }
@@ -417,7 +427,7 @@ export default class InnerRouter {
 
 		// if the route is a live preview init and we have a scrollY stored
 		// scroll to that
-		if (route.origin === 'live-preview-init') {
+		if (req.origin === 'live-preview-init') {
 			const scrollY = sessionStorage.getItem('live-preview-scroll');
 			if (scrollY) {
 				scrollTo = {
@@ -427,11 +437,11 @@ export default class InnerRouter {
 			}
 			// if we have a hash and the route was not visited
 		} else if (
-			route.hash &&
-			((route.origin === 'init' && typeof route.scrollY !== 'number') ||
-				route.origin === 'click')
+			req.hash &&
+			((req.origin === 'init' && typeof req.scrollY !== 'number') ||
+				req.origin === 'click')
 		) {
-			const el = document.getElementById(route.hash.substring(1));
+			const el = document.getElementById(req.hash.substring(1));
 			if (el) {
 				scrollTo = {
 					intoView: el,
@@ -443,11 +453,11 @@ export default class InnerRouter {
 		// restore scroll position
 		if (
 			!scrollTo &&
-			route.origin !== 'click' &&
-			typeof route.scrollY === 'number'
+			req.origin !== 'click' &&
+			typeof req.scrollY === 'number'
 		) {
 			scrollTo = {
-				top: route.scrollY,
+				top: req.scrollY,
 				behavior: 'instant',
 			};
 		}

package/src/routing/PageLoader.ts

@@ -1,4 +1,4 @@
-import Route from './Route.js';
+import Request from './Request.js';
 import Site from './Site.js';
 
 export type PageLoaderOptions = {
@@ -11,7 +11,7 @@ export type LoadResponse = {
 };
 
 export type LoadFn = (
-	route: Route,
+	req: Request,
 	site: Site,
 	opts: LoadOptions,
 ) => Promise<any> | any;
@@ -31,7 +31,7 @@ export default class PageLoader<More> {
 
 	onLoaded: (
 		resp: LoadResponse,
-		route: Route,
+		req: Request,
 		site: Site,
 		more: More,
 	) => void;
@@ -62,7 +62,7 @@ export default class PageLoader<More> {
 		this.onProgress(false);
 	}
 
-	async load(route: Route, site: Site, more: More) {
+	async load(req: Request, site: Site, more: More) {
 		this.onProgress(true);
 
 		const version = ++this.loadingVersion;
@@ -76,7 +76,7 @@ export default class PageLoader<More> {
 
 		const resp: LoadResponse = { success: false, data: null };
 		try {
-			resp.data = await this.loadFn(route, site, { setProgress });
+			resp.data = await this.loadFn(req, site, { setProgress });
 			resp.success = true;
 		} catch (e) {
 			resp.success = false;
@@ -91,19 +91,19 @@ export default class PageLoader<More> {
 			return console.log('route changed quickly, ignoring response');
 
 		this.onProgress(false);
-		this.onLoaded(resp, route, site, more);
+		this.onLoaded(resp, req, site, more);
 	}
 
 	// you don't need to wait on this call
-	async preload(route: Route, site: Site) {
-		const url = route.url.origin + route.url.pathname;
+	async preload(req: Request, site: Site) {
+		const url = req.url.origin + req.url.pathname;
 		if (this.preloadedUrls.has(url)) return;
 
 		this.preloadedUrls.add(url);
 
 		try {
-			await this.loadFn(route, site, { setProgress: () => null });
-		} catch (e) {
+			await this.loadFn(req, site, { setProgress: () => null });
+		} catch (_e) {
 			console.log('preload failed');
 			// retry at another time
 			this.preloadedUrls.delete(url);