@hybridly/core 0.0.1-dev.3 → 0.1.0-alpha.0

package/dist/index.d.ts

@@ -1,138 +1,100 @@
 import { RequestData } from '@hybridly/utils';
-import { AxiosResponse, AxiosProgressEvent } from 'axios';
+import { AxiosResponse, AxiosProgressEvent, Axios } from 'axios';
 
-declare type MaybePromise<T> = T | Promise<T>;
+type MaybePromise<T> = T | Promise<T>;
 
-interface Hooks {
+interface RequestHooks {
     /**
-     * Called before anything when a visit is going to happen.
-     */
-    before: (options: VisitOptions) => MaybePromise<any | boolean>;
+         * Called before a navigation request is going to happen.
+         */
+    before: (options: HybridRequestOptions, context: InternalRouterContext) => MaybePromise<any | boolean>;
     /**
-     * Called before the request of a visit is going to happen.
+     * Called before the request of a navigation is going to happen.
      */
     start: (context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when progress on the request is being made.
      */
-    progress: (progress: Progress) => MaybePromise<any>;
+    progress: (progress: Progress, context: InternalRouterContext) => MaybePromise<any>;
     /**
-     * Called when data is received after a request for a visit.
+     * Called when data is received after a request for a navigation.
      */
-    data: (response: AxiosResponse) => MaybePromise<any>;
+    data: (response: AxiosResponse, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a request is successful and there is no error.
      */
-    success: (payload: VisitPayload) => MaybePromise<any>;
+    success: (payload: HybridPayload, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a request is successful but there were errors.
      */
-    error: (errors: Errors) => MaybePromise<any>;
+    error: (errors: Errors, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a request has been aborted.
      */
     abort: (context: InternalRouterContext) => MaybePromise<any>;
     /**
-     * Called when a response to a request is not a valid Hybridly response.
+     * Called when a response to a request is not a valid hybrid response.
      */
-    invalid: (response: AxiosResponse) => MaybePromise<void>;
+    invalid: (response: AxiosResponse, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when an unknowne exception was triggered.
      */
-    exception: (error: Error) => MaybePromise<void>;
+    exception: (error: Error, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called whenever the request failed, for any reason, in addition to other hooks.
      */
-    fail: (context: InternalRouterContext) => MaybePromise<void>;
+    fail: (context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called after a request has been made, even if it didn't succeed.
      */
-    after: (context: InternalRouterContext) => MaybePromise<void>;
+    after: (context: InternalRouterContext) => MaybePromise<any>;
+}
+interface Hooks extends RequestHooks {
+    /**
+         * Called when Hybridly's context is initialized.
+         */
+    initialized: (context: InternalRouterContext) => MaybePromise<any>;
+    /**
+     * Called after Hybridly's initial page load.
+     */
+    ready: (context: InternalRouterContext) => MaybePromise<any>;
+    /**
+     * Called when a back-forward navigation occurs.
+     */
+    backForward: (state: any, context: InternalRouterContext) => MaybePromise<any>;
+    /**
+     * Called when a component navigation is being made.
+     */
+    navigating: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
-     * Called when a visit has been made and a page component has been navigated to.
+     * Called when a component has been navigated to.
      */
-    navigate: (options: NavigationOptions) => MaybePromise<void>;
+    navigated: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+}
+interface HookOptions {
+    /** Executes the hook only once. */
+    once?: boolean;
 }
 /**
  * Registers a global hook.
  */
-declare function registerHook<T extends keyof Hooks>(hook: T, fn: Hooks[T]): () => void;
-/**
- * Registers a global hook that will run only once.
- */
-declare function registerHookOnce<T extends keyof Hooks>(hook: T, fn: Hooks[T]): void;
+declare function registerHook<T extends keyof Hooks>(hook: T, fn: Hooks[T], options?: HookOptions): () => void;
 
-interface Plugin {
+interface Plugin extends Partial<Hooks> {
+    /** Identifier of the plugin. */
     name: string;
-    initialized: (context: InternalRouterContext) => MaybePromise<void>;
-    hooks: Partial<Hooks>;
 }
 declare function definePlugin(plugin: Plugin): Plugin;
 
-/** Options for creating a router context. */
-interface RouterContextOptions {
-    /** The initial payload served by the browser. */
-    payload: VisitPayload;
-    /** Adapter-specific functions. */
-    adapter: Adapter;
-    /** History state serializer. */
-    serializer?: Serializer;
-    /** List of plugins. */
-    plugins?: Plugin[];
-}
-/** Router context. */
-interface InternalRouterContext {
-    /** The current, normalized URL. */
-    url: string;
-    /** The current view. */
-    view: View;
-    /** The current, optional dialog. */
-    dialog?: View;
-    /** The current local asset version. */
-    version: string;
-    /** The current adapter's functions. */
-    adapter: Adapter;
-    /** Scroll positions of the current page's DOM elements. */
-    scrollRegions: ScrollRegion[];
-    /** Arbitrary state. */
-    state: Record<string, any>;
-    /** Currently pending visit. */
-    activeVisit?: PendingVisit;
-    /** History state serializer. */
-    serializer: Serializer;
-    /** List of plugins. */
-    plugins: Plugin[];
-    /** Global hooks. */
-    hooks: Partial<Record<keyof Hooks, Array<Function>>>;
-}
-/** Router context. */
-declare type RouterContext = Readonly<InternalRouterContext>;
-/** Adapter-specific functions. */
-interface Adapter {
-    /** Resolves a component from the given name. */
-    resolveComponent: ResolveComponent;
-    /** Swaps to the given view. */
-    swapView: SwapView;
-    /** Swaps to the given dialog. */
-    swapDialog: SwapDialog;
-    /** Called when the context is updated. */
-    update?: (context: InternalRouterContext) => void;
-}
-interface ScrollRegion {
-    top: number;
-    left: number;
-}
-/** Provides methods to serialize the state into the history state. */
-interface Serializer {
-    serialize: <T>(view: T) => any;
-    unserialize: <T>(state: any) => T;
+interface CloseDialogOptions extends HybridRequestOptions {
 }
 
-/** Gets the current context. */
-declare function getRouterContext(): RouterContext;
-
-declare type UrlResolvable = string | URL | Location;
-declare type UrlTransformable = Partial<Omit<URL, 'searchParams' | 'toJSON' | 'toString'>>;
+type UrlResolvable = string | URL | Location;
+type UrlTransformable = BaseUrlTransformable | ((string: URL) => BaseUrlTransformable);
+type BaseUrlTransformable = Partial<Omit<URL, 'searchParams' | 'toJSON' | 'toString'>> & {
+    query?: any;
+    trailingSlash?: boolean;
+};
 /**
  * Converts an input to an URL, optionally changing its properties after initialization.
  */
@@ -142,12 +104,12 @@ declare function makeUrl(href: UrlResolvable, transformations?: UrlTransformable
  */
 declare function sameUrls(...hrefs: UrlResolvable[]): boolean;
 
-declare type ConditionalNavigationOption = boolean | ((payload: VisitPayload) => boolean);
-interface LocalVisitOptions {
+type ConditionalNavigationOption = boolean | ((payload: HybridPayload) => boolean);
+interface ComponentNavigationOptions {
     /** Name of the component to use. */
     component?: string;
     /** Properties to apply to the component. */
-    properties: Properties;
+    properties?: Properties;
     /**
      * Whether to replace the current history state instead of adding
      * one. This affects the browser's "back" and "forward" features.
@@ -160,7 +122,7 @@ interface LocalVisitOptions {
 }
 interface NavigationOptions {
     /** View to navigate to. */
-    payload?: VisitPayload;
+    payload?: HybridPayload;
     /**
      * Whether to replace the current history state instead of adding
      * one. This affects the browser's "back" and "forward" features.
@@ -188,62 +150,79 @@ interface NavigationOptions {
      */
     updateHistoryState?: boolean;
     /**
-     * Defines whether this navigation is a back/forward visit from the popstate event.
+     * Defines whether this navigation is a back/forward navigation from the popstate event.
      * @internal This is an advanced property meant to be used internally.
      */
     isBackForward?: boolean;
 }
-declare type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-interface VisitOptions extends Omit<NavigationOptions, 'request'> {
-    /** The URL to visit. */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface HybridRequestOptions extends Omit<NavigationOptions, 'payload'> {
+    /** The URL to navigation. */
     url?: UrlResolvable;
     /** HTTP verb to use for the request. */
-    method?: Method;
+    method?: Method | Lowercase<Method>;
     /** Body of the request. */
     data?: RequestData;
-    /** Which properties to update for this visit. Other properties will be ignored. */
+    /** Which properties to update for this navigation. Other properties will be ignored. */
     only?: string | string[];
-    /** Which properties not to update for this visit. Other properties will be updated. */
+    /** Which properties not to update for this navigation. Other properties will be updated. */
     except?: string | string[];
     /** Specific headers to add to the request. */
     headers?: Record<string, string>;
     /** The bag in which to put potential errors. */
     errorBag?: string;
-    /** Hooks for this visit. */
-    hooks?: Partial<Hooks>;
+    /** Hooks for this navigation. */
+    hooks?: Partial<RequestHooks>;
     /** If `true`, force the usage of a `FormData` object. */
     useFormData?: boolean;
+    /**
+     * If `false`, disable automatic form spoofing.
+     * @see https://laravel.com/docs/9.x/routing#form-method-spoofing
+     */
+    spoof?: boolean;
+    /**
+     * If `false`, does not trigger the progress bar for this request.
+     */
+    progress?: boolean;
 }
-interface VisitResponse {
+interface NavigationResponse {
     response?: AxiosResponse;
     error?: {
         type: string;
         actual: Error;
     };
 }
+interface DialogRouter {
+    /** Closes the current dialog. */
+    close: (options?: CloseDialogOptions) => void;
+}
 interface Router {
-    /** Aborts the currently pending visit, if any. */
+    /** Aborts the currently pending navigate, if any. */
     abort: () => Promise<void>;
-    /** Checks if there is an active request. */
+    /** Checks if there is an active navigate. */
     active: () => boolean;
-    /** Makes a visit with the given options. */
-    visit: (options: VisitOptions) => Promise<VisitResponse>;
+    /** Makes a navigate with the given options. */
+    navigate: (options: HybridRequestOptions) => Promise<NavigationResponse>;
     /** Reloads the current page. */
-    reload: (options?: VisitOptions) => Promise<VisitResponse>;
+    reload: (options?: HybridRequestOptions) => Promise<NavigationResponse>;
+    /** Makes a request to given named route. The HTTP verb is determined automatically but can be overriden. */
+    to: <T extends RouteName>(name: T, parameters?: RouteParameters<T>, options?: Omit<HybridRequestOptions, 'url'>) => Promise<NavigationResponse>;
     /** Makes a GET request to the given URL. */
-    get: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    get: (url: UrlResolvable, options?: Omit<HybridRequestOptions, 'method' | 'url'>) => Promise<NavigationResponse>;
     /** Makes a POST request to the given URL. */
-    post: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    post: (url: UrlResolvable, options?: Omit<HybridRequestOptions, 'method' | 'url'>) => Promise<NavigationResponse>;
     /** Makes a PUT request to the given URL. */
-    put: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    put: (url: UrlResolvable, options?: Omit<HybridRequestOptions, 'method' | 'url'>) => Promise<NavigationResponse>;
     /** Makes a PATCH request to the given URL. */
-    patch: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    patch: (url: UrlResolvable, options?: Omit<HybridRequestOptions, 'method' | 'url'>) => Promise<NavigationResponse>;
     /** Makes a DELETE request to the given URL. */
-    delete: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
-    /** Navigates to the given external URL. Alias for `document.location.href`. */
-    external: (url: UrlResolvable, data?: VisitOptions['data']) => void;
+    delete: (url: UrlResolvable, options?: Omit<HybridRequestOptions, 'method' | 'url'>) => Promise<NavigationResponse>;
+    /** Navigates to the given external URL. Convenience method using `document.location.href`. */
+    external: (url: UrlResolvable, data?: HybridRequestOptions['data']) => void;
     /** Navigates to the given URL without a server round-trip. */
-    local: (url: UrlResolvable, options: LocalVisitOptions) => Promise<void>;
+    local: (url: UrlResolvable, options: ComponentNavigationOptions) => Promise<void>;
+    /** Access the dialog router. */
+    dialog: DialogRouter;
     /** Access the history state. */
     history: {
         /** Remembers a value for the given route. */
@@ -252,45 +231,57 @@ interface Router {
         get: <T = any>(key: string) => T | undefined;
     };
 }
-/** An axios visit being made. */
-interface PendingVisit {
+/** A navigation being made. */
+interface PendingNavigation {
     /** The URL to which the request is being made. */
     url: URL;
     /** Abort controller associated to this request. */
     controller: AbortController;
-    /** Options for the associated visit. */
-    options: VisitOptions;
-    /** Visit identifier. */
+    /** Options for the associated hybrid request. */
+    options: HybridRequestOptions;
+    /** Navigation identifier. */
     id: string;
+    /** Current status. */
+    status: 'pending' | 'success' | 'error';
 }
 /** A page or dialog component. */
 interface View {
     /** Name of the component to use. */
-    name: string;
+    component: string;
     /** Properties to apply to the component. */
     properties: Properties;
 }
-declare type Property = null | string | number | boolean | Property[] | {
+interface Dialog extends View {
+    /** URL that is the base background page when navigating to the dialog directly. */
+    baseUrl: string;
+    /** URL to which the dialog should redirect when closed. */
+    redirectUrl: string;
+    /** Unique identifier for this modal's lifecycle. */
+    key: string;
+}
+type Property = null | string | number | boolean | Property[] | {
     [name: string]: Property;
 };
-declare type Properties = Record<string | number, Property>;
+type Properties = Record<string | number, Property>;
 interface SwapOptions<T> {
     /** The new component. */
     component: T;
+    /** The new properties. */
+    properties?: any;
     /** Whether to preserve the state of the component. */
     preserveState?: boolean;
+    /** Current dialog. */
+    dialog?: Dialog;
 }
-declare type ViewComponent = any;
-declare type DialogComponent = any;
-declare type ResolveComponent = (name: string) => Promise<ViewComponent>;
-declare type SwapView = (options: SwapOptions<ViewComponent>) => Promise<void>;
-declare type SwapDialog = (options: SwapOptions<DialogComponent>) => Promise<void>;
-/** The payload of a visit request from the server. */
-interface VisitPayload {
+type ViewComponent = any;
+type ResolveComponent = (name: string) => Promise<ViewComponent>;
+type SwapView = (options: SwapOptions<ViewComponent>) => Promise<void>;
+/** The payload of a navigation request from the server. */
+interface HybridPayload {
     /** The view to use in this request. */
     view: View;
     /** An optional dialog. */
-    dialog?: View;
+    dialog?: Dialog;
     /** The current page URL. */
     url: string;
     /** The current asset version. */
@@ -306,11 +297,107 @@ interface Errors {
     [key: string]: string;
 }
 
+interface RoutingConfiguration {
+    url: string;
+    port?: number;
+    defaults: Record<string, any>;
+    routes: Record<string, RouteDefinition>;
+}
+interface RouteDefinition {
+    uri: string;
+    method: Method[];
+    bindings: Record<string, string>;
+    domain?: string;
+    wheres?: Record<string, string>;
+    name: string;
+}
+interface GlobalRouteCollection extends RoutingConfiguration {
+}
+type RouteName = keyof GlobalRouteCollection['routes'];
+type RouteParameters<T extends RouteName> = Record<keyof GlobalRouteCollection['routes'][T]['bindings'], any> & Record<string, any>;
+
+/** Options for creating a router context. */
+interface RouterContextOptions {
+    /** The initial payload served by the browser. */
+    payload: HybridPayload;
+    /** Adapter-specific functions. */
+    adapter: Adapter;
+    /** History state serializer. */
+    serializer?: Serializer;
+    /** List of plugins. */
+    plugins?: Plugin[];
+    /** The Axios instance. */
+    axios?: Axios;
+    /** Initial routing configuration. */
+    routing?: RoutingConfiguration;
+    /** Whether to display response error modals. */
+    responseErrorModals?: boolean;
+}
+/** Router context. */
+interface InternalRouterContext {
+    /** The current, normalized URL. */
+    url: string;
+    /** The current view. */
+    view: View;
+    /** The current, optional dialog. */
+    dialog?: Dialog;
+    /** The current local asset version. */
+    version: string;
+    /** The current adapter's functions. */
+    adapter: ResolvedAdapter;
+    /** Scroll positions of the current page's DOM elements. */
+    scrollRegions: ScrollRegion[];
+    /** Arbitrary state. */
+    state: Record<string, any>;
+    /** Currently pending navigation. */
+    pendingNavigation?: PendingNavigation;
+    /** History state serializer. */
+    serializer: Serializer;
+    /** List of plugins. */
+    plugins: Plugin[];
+    /** Global hooks. */
+    hooks: Partial<Record<keyof Hooks, Array<Function>>>;
+    /** The Axios instance. */
+    axios: Axios;
+    /** Routing configuration. */
+    routing?: RoutingConfiguration;
+    /** Whether to display response error modals. */
+    responseErrorModals?: boolean;
+}
+/** Router context. */
+type RouterContext = Readonly<InternalRouterContext>;
+/** Adapter-specific functions. */
+interface Adapter {
+    /** Resolves a component from the given name. */
+    resolveComponent: ResolveComponent;
+    /** Called when the view is swapped. */
+    onViewSwap: SwapView;
+    /** Called when the context is updated. */
+    onContextUpdate?: (context: InternalRouterContext) => void;
+    /** Called when a dialog is closed. */
+    onDialogClose?: (context: InternalRouterContext) => void;
+}
+interface ResolvedAdapter extends Adapter {
+    updateRoutingConfiguration: (routing?: RoutingConfiguration) => void;
+}
+interface ScrollRegion {
+    top: number;
+    left: number;
+}
+/** Provides methods to serialize the state into the history state. */
+interface Serializer {
+    serialize: <T>(view: T) => any;
+    unserialize: <T>(state: any) => T;
+}
+
+/** Gets the current context. */
+declare function getRouterContext(): RouterContext;
+
 /**
  * The hybridly router.
  * This is the core function that you can use to navigate in
  * your application. Make sure the routes you call return a
- * hybridly response, otherwise you need to call `external`.
+ * hybrid response, otherwise you need to call `external`.
  *
  * @example
  * router.get('/posts/edit', { post })
@@ -328,11 +415,22 @@ interface Authorizable<Authorizations extends Record<string, boolean>> {
  */
 declare function can<Authorizations extends Record<string, boolean>, Data extends Authorizable<Authorizations>, Action extends keyof Data['authorization']>(resource: Data, action: Action): Authorizations[Action];
 
+/**
+ * Generates a route from the given route name.
+ */
+declare function route<T extends RouteName>(name: T, parameters?: RouteParameters<T>, absolute?: boolean): string;
+/**
+ * Determines if the current route correspond to the given route name and parameters.
+ */
+declare function current<T extends RouteName>(name: T, parameters?: RouteParameters<T>, mode?: 'loose' | 'strict'): boolean;
+
 declare const STORAGE_EXTERNAL_KEY = "hybridly:external";
-declare const HYBRIDLY_HEADER = "x-hybridly";
-declare const EXTERNAL_VISIT_HEADER: string;
+declare const HYBRIDLY_HEADER = "x-hybrid";
+declare const EXTERNAL_NAVIGATION_HEADER: string;
 declare const PARTIAL_COMPONENT_HEADER: string;
 declare const ONLY_DATA_HEADER: string;
+declare const DIALOG_KEY_HEADER: string;
+declare const DIALOG_REDIRECT_HEADER: string;
 declare const EXCEPT_DATA_HEADER: string;
 declare const CONTEXT_HEADER: string;
 declare const VERSION_HEADER: string;
@@ -341,9 +439,11 @@ declare const SCROLL_REGION_ATTRIBUTE = "scroll-region";
 
 declare const constants_STORAGE_EXTERNAL_KEY: typeof STORAGE_EXTERNAL_KEY;
 declare const constants_HYBRIDLY_HEADER: typeof HYBRIDLY_HEADER;
-declare const constants_EXTERNAL_VISIT_HEADER: typeof EXTERNAL_VISIT_HEADER;
+declare const constants_EXTERNAL_NAVIGATION_HEADER: typeof EXTERNAL_NAVIGATION_HEADER;
 declare const constants_PARTIAL_COMPONENT_HEADER: typeof PARTIAL_COMPONENT_HEADER;
 declare const constants_ONLY_DATA_HEADER: typeof ONLY_DATA_HEADER;
+declare const constants_DIALOG_KEY_HEADER: typeof DIALOG_KEY_HEADER;
+declare const constants_DIALOG_REDIRECT_HEADER: typeof DIALOG_REDIRECT_HEADER;
 declare const constants_EXCEPT_DATA_HEADER: typeof EXCEPT_DATA_HEADER;
 declare const constants_CONTEXT_HEADER: typeof CONTEXT_HEADER;
 declare const constants_VERSION_HEADER: typeof VERSION_HEADER;
@@ -353,9 +453,11 @@ declare namespace constants {
   export {
     constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY,
     constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER,
-    constants_EXTERNAL_VISIT_HEADER as EXTERNAL_VISIT_HEADER,
+    constants_EXTERNAL_NAVIGATION_HEADER as EXTERNAL_NAVIGATION_HEADER,
     constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER,
     constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER,
+    constants_DIALOG_KEY_HEADER as DIALOG_KEY_HEADER,
+    constants_DIALOG_REDIRECT_HEADER as DIALOG_REDIRECT_HEADER,
     constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER,
     constants_CONTEXT_HEADER as CONTEXT_HEADER,
     constants_VERSION_HEADER as VERSION_HEADER,
@@ -364,4 +466,4 @@ declare namespace constants {
   };
 }
 
-export { Authorizable, MaybePromise, Method, Plugin, ResolveComponent, Router, RouterContext, RouterContextOptions, UrlResolvable, VisitOptions, VisitPayload, VisitResponse, can, constants, createRouter, definePlugin, getRouterContext, makeUrl, registerHook, registerHookOnce, router, sameUrls };
+export { Authorizable, GlobalRouteCollection, HybridPayload, HybridRequestOptions, MaybePromise, Method, NavigationResponse, Plugin, Progress, ResolveComponent, RouteDefinition, RouteName, RouteParameters, Router, RouterContext, RouterContextOptions, RoutingConfiguration, UrlResolvable, can, constants, createRouter, current, definePlugin, getRouterContext, makeUrl, registerHook, route, router, sameUrls };