piral-core 1.0.0-pre.2296 → 1.0.1-beta.5640

package/lib/types/components.d.ts

@@ -1,7 +1,8 @@
-import type { ComponentType } from 'react';
-import type { RouteComponentProps } from 'react-router';
+import type { ComponentType, ReactNode } from 'react';
+import type { RouteComponentProps, SwitchProps } from 'react-router';
 import type { FirstParametersOf, UnionOf } from './common';
 import type { PiralCustomErrors, PiralCustomComponentConverters } from './custom';
+import type { NavigationApi } from './navigation';
 import type { LayoutType } from './layout';
 /**
  * Mapping of available component converters.
@@ -30,7 +31,19 @@ export interface HtmlComponent<TProps> {
  * The context to be transported into the generic components.
  */
 export interface ComponentContext {
-    router: RouteComponentProps;
+    /**
+     * The router-independent navigation API.
+     */
+    navigation: NavigationApi;
+    /**
+     * The internal router object.
+     * @deprecated Exposes internals that can change at any time.
+     */
+    router: any;
+    /**
+     * The public path of the application.
+     */
+    publicPath: string;
 }
 /**
  * Generic definition of a framework-independent component.
@@ -41,25 +54,28 @@ export interface ForeignComponent<TProps> {
      * @param element The container hosting the element.
      * @param props The props to transport.
      * @param ctx The associated context.
+     * @param locals The local state of this component instance.
      */
-    mount(element: HTMLElement, props: TProps, ctx: ComponentContext): void;
+    mount(element: HTMLElement, props: TProps, ctx: ComponentContext, locals: Record<string, any>): void;
     /**
      * Called when the component should be updated.
      * @param element The container hosting the element.
      * @param props The props to transport.
      * @param ctx The associated context.
+     * @param locals The local state of this component instance.
      */
-    update?(element: HTMLElement, props: TProps, ctx: ComponentContext): void;
+    update?(element: HTMLElement, props: TProps, ctx: ComponentContext, locals: Record<string, any>): void;
     /**
      * Called when a component is unmounted.
      * @param element The container that was hosting the element.
+     * @param locals The local state of this component instance.
      */
-    unmount?(element: HTMLElement): void;
+    unmount?(element: HTMLElement, locals: Record<string, any>): void;
 }
 /**
  * Possible shapes for a component.
  */
-export declare type AnyComponent<T> = ComponentType<T> | FirstParametersOf<ComponentConverters<T>>;
+export type AnyComponent<T> = ComponentType<T> | FirstParametersOf<ComponentConverters<T>>;
 /**
  * The error used when a route cannot be resolved.
  */
@@ -81,6 +97,10 @@ export interface PageErrorInfoProps extends RouteComponentProps {
      * The provided error details.
      */
     error: any;
+    /**
+     * The name of the pilet emitting the error.
+     */
+    pilet?: string;
 }
 /**
  * The error used when the app could not be loaded.
@@ -107,6 +127,10 @@ export interface ExtensionErrorInfoProps {
      * The provided error details.
      */
     error: any;
+    /**
+     * The name of the pilet emitting the error.
+     */
+    pilet?: string;
 }
 /**
  * The error used when the exact type is unknown.
@@ -120,6 +144,10 @@ export interface UnknownErrorInfoProps {
      * The provided error details.
      */
     error: any;
+    /**
+     * The name of the pilet emitting the error.
+     */
+    pilet?: string;
 }
 /**
  * Map of all error types to their respective props.
@@ -149,7 +177,7 @@ export interface Errors extends PiralCustomErrors {
 /**
  * The props for the ErrorInfo component.
  */
-export declare type ErrorInfoProps = UnionOf<Errors>;
+export type ErrorInfoProps = UnionOf<Errors>;
 /**
  * The props of a Loading indicator component.
  */
@@ -163,9 +191,47 @@ export interface LayoutProps {
      * The currently selected layout type.
      */
     currentLayout: LayoutType;
+    /**
+     * The page's content.
+     */
+    children: ReactNode;
 }
 /**
  * The props of a Router component.
  */
 export interface RouterProps {
+    /**
+     * The content to be rendered inside the router.
+     */
+    children?: ReactNode;
+    /**
+     * The public path to use.
+     */
+    publicPath: string;
+}
+/**
+ * Represents a path in the app registration.
+ */
+export interface AppPath {
+    /**
+     * The exact path to use.
+     */
+    path: string;
+    /**
+     * The component to register for this path.
+     */
+    Component: ComponentType<RouteComponentProps>;
+}
+/**
+ * The props of the RouteSwitch component.
+ */
+export interface RouteSwitchProps extends SwitchProps {
+    /**
+     * The component that should be used in case nothing was found.
+     */
+    NotFound: ComponentType<RouteComponentProps>;
+    /**
+     * The component to register for the different paths.
+     */
+    paths: Array<AppPath>;
 }

package/lib/types/config.d.ts

@@ -1,20 +1,25 @@
-import type { PiletRequester, PiletDependencyFetcher, PiletDependencyGetter, PiletLoadingStrategy, PiletLoader, Pilet, AvailableDependencies, CustomSpecLoaders, DefaultLoaderConfig, PiletApiCreator } from 'piral-base';
+import type { PiletRequester, PiletLoadingStrategy, PiletLoader, Pilet, AvailableDependencies, CustomSpecLoaders, DefaultLoaderConfig, PiletApiCreator } from 'piral-base';
+import { DebuggerExtensionOptions } from 'piral-debug-utils';
 import type { NestedPartial } from './common';
 import type { PiralPlugin } from './plugin';
 import type { GlobalState, GlobalStateContext, PiralDefineActions } from './state';
-export { PiletLoadingStrategy, PiletDependencyFetcher, PiletDependencyGetter, PiletRequester, AvailableDependencies };
+export { PiletLoadingStrategy, PiletRequester, AvailableDependencies };
 /**
- * The configuration for loading the pilets of the Piral instance.
+ * Definition for customizing the shared dependencies.
  */
-export interface PiralPiletConfiguration {
-    /**
-     * The callback for defining how a dependency will be fetched.
-     */
-    fetchDependency?: PiletDependencyFetcher;
+export interface DependencySelector {
     /**
-     * Function to get the dependencies for a given module.
+     * Selects the dependencies to share from the currently available dependencies.
+     * @param currentDependencies The currently available dependencies.
+     * @default currentDependencies All current dependencies are shared
+     * @returns The dependencies selected to be shared.
      */
-    getDependencies?: PiletDependencyGetter;
+    (currentDependencies: AvailableDependencies): AvailableDependencies;
+}
+/**
+ * The configuration for loading the pilets of the Piral instance.
+ */
+export interface PiralPiletConfiguration {
     /**
      * Function to load the modules asynchronously, e.g., from a server 🚚.
      */
@@ -31,6 +36,10 @@ export interface PiralPiletConfiguration {
      * Optionally, configures the default loader.
      */
     loaderConfig?: DefaultLoaderConfig;
+    /**
+     * Optionally, configures explicitly what dependencies are shared.
+     */
+    shareDependencies?: DependencySelector;
     /**
      * Determines that pilets are loaded asynchronously, essentially showing the
      * app right away without waiting for the pilets to load and evaluate.
@@ -42,12 +51,6 @@ export interface PiralPiletConfiguration {
      * This can be used for customization or for debugging purposes.
      */
     availablePilets?: Array<Pilet>;
-    /**
-     * Optionally provides a function to extend the API creator with some additional
-     * functionality.
-     * @deprecated Use plugins instead.
-     */
-    extendApi?: PiralPlugin | Array<PiralPlugin>;
     /**
      * Extends the Piral instance with additional capabilities.
      */
@@ -80,8 +83,12 @@ export interface PiralStateConfiguration {
      * Optionally, sets up some initial custom actions ⚡️.
      */
     actions?: PiralDefineActions;
+    /**
+     * Optionally, sets up additional configuration for the debug tooling 🤖.
+     */
+    debug?: DebuggerExtensionOptions;
 }
 /**
  * The configuration to be used in the Piral instance.
  */
-export declare type PiralConfiguration = PiralPiletConfiguration & PiralStateConfiguration;
+export type PiralConfiguration = PiralPiletConfiguration & PiralStateConfiguration;

package/lib/types/data.d.ts

@@ -10,7 +10,7 @@ export interface SharedData<TValue = any> {
 /**
  * Defines the potential targets when storing data.
  */
-export declare type DataStoreTarget = 'memory' | 'local' | 'remote';
+export type DataStoreTarget = 'memory' | 'local' | 'remote';
 /**
  * Defines the custom options for storing data.
  */
@@ -27,7 +27,7 @@ export interface CustomDataStoreOptions {
 /**
  * Defines the options to be used for storing data.
  */
-export declare type DataStoreOptions = DataStoreTarget | CustomDataStoreOptions;
+export type DataStoreOptions = DataStoreTarget | CustomDataStoreOptions;
 /**
  * Defines the shape of a shared data item.
  */

package/lib/types/extension.d.ts

@@ -1,5 +1,6 @@
-/// <reference types="react" />
+import type { ReactNode, ReactElement } from 'react';
 import type { PiralCustomExtensionSlotMap } from './custom';
+import type { ExtensionRegistration } from './state';
 /**
  * The mapping of the existing (known) extension slots.
  */
@@ -9,16 +10,38 @@ export interface PiralExtensionSlotMap extends PiralCustomExtensionSlotMap {
  * The basic props for defining an extension slot.
  */
 export interface BaseExtensionSlotProps<TName, TParams> {
+    /**
+     * The children to transport, if any.
+     */
+    children?: ReactNode;
     /**
      * Defines what should be rendered when no components are available
      * for the specified extension.
      */
-    empty?(): React.ReactNode;
+    empty?(): ReactNode;
+    /**
+     * Determines if the `render` function should be called in case no
+     * components are available for the specified extension.
+     *
+     * If true, `empty` will be called and returned from the slot.
+     * If false, `render` will be called with the result of calling `empty`.
+     * The result of calling `render` will then be returned from the slot.
+     */
+    emptySkipsRender?: boolean;
+    /**
+     * Defines the order of the components to render.
+     * May be more convient than using `render` w.r.t. ordering extensions
+     * by their supplied metadata.
+     * @param extensions The registered extensions.
+     * @returns The ordered extensions.
+     */
+    order?(extensions: Array<ExtensionRegistration>): Array<ExtensionRegistration>;
     /**
      * Defines how the provided nodes should be rendered.
      * @param nodes The rendered extension nodes.
+     * @returns The rendered nodes, i.e., an ReactElement.
      */
-    render?(nodes: Array<React.ReactNode>): React.ReactElement<any, any> | null;
+    render?(nodes: Array<ReactNode>): ReactElement<any, any> | null;
     /**
      * The custom parameters for the given extension.
      */
@@ -28,7 +51,11 @@ export interface BaseExtensionSlotProps<TName, TParams> {
      */
     name: TName;
 }
+/**
+ * Gives the extension params shape for the given extension slot name.
+ */
+export type ExtensionParams<TName> = TName extends keyof PiralExtensionSlotMap ? PiralExtensionSlotMap[TName] : TName extends string ? any : TName;
 /**
  * The props for defining an extension slot.
  */
-export declare type ExtensionSlotProps<K = string> = BaseExtensionSlotProps<K extends string ? K : string, K extends keyof PiralExtensionSlotMap ? PiralExtensionSlotMap[K] : K extends string ? any : K>;
+export type ExtensionSlotProps<TName = string> = BaseExtensionSlotProps<TName extends string ? TName : string, ExtensionParams<TName>>;

package/lib/types/index.d.ts

@@ -7,6 +7,7 @@ export * from './data';
 export * from './extension';
 export * from './instance';
 export * from './layout';
+export * from './navigation';
 export * from './plugin';
 export * from './state';
 export * from './utils';

package/lib/types/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-var tslib_1 = require("tslib");
+const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./api"), exports);
 tslib_1.__exportStar(require("./common"), exports);
 tslib_1.__exportStar(require("./components"), exports);
@@ -10,6 +10,7 @@ tslib_1.__exportStar(require("./data"), exports);
 tslib_1.__exportStar(require("./extension"), exports);
 tslib_1.__exportStar(require("./instance"), exports);
 tslib_1.__exportStar(require("./layout"), exports);
+tslib_1.__exportStar(require("./navigation"), exports);
 tslib_1.__exportStar(require("./plugin"), exports);
 tslib_1.__exportStar(require("./state"), exports);
 tslib_1.__exportStar(require("./utils"), exports);

package/lib/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;AAAA,gDAAsB;AACtB,mDAAyB;AACzB,uDAA6B;AAC7B,mDAAyB;AACzB,mDAAyB;AACzB,iDAAuB;AACvB,sDAA4B;AAC5B,qDAA2B;AAC3B,mDAAyB;AACzB,mDAAyB;AACzB,kDAAwB;AACxB,kDAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;AAAA,gDAAsB;AACtB,mDAAyB;AACzB,uDAA6B;AAC7B,mDAAyB;AACzB,mDAAyB;AACzB,iDAAuB;AACvB,sDAA4B;AAC5B,qDAA2B;AAC3B,mDAAyB;AACzB,uDAA6B;AAC7B,mDAAyB;AACzB,kDAAwB;AACxB,kDAAwB"}

package/lib/types/instance.d.ts

@@ -1,24 +1,46 @@
+import type { ReactNode } from 'react';
 import type { PiletApi, PiletApiCreator, LoadPiletsOptions, EventEmitter } from 'piral-base';
 import type { GlobalStateContext } from './state';
 import type { LayoutBreakpoints } from './layout';
+import type { PiralConfiguration } from './config';
 /**
- * The props of the Piral component.
+ * The props of the Piral context.
  */
-export interface PortalProps {
+export interface PiralContextProps {
     /**
      * The specific Piral instance to be used.
      */
     instance?: PiralInstance;
+    children?: ReactNode;
+}
+/**
+ * The props of the Piral component.
+ */
+export interface PiralProps extends PiralContextProps {
     /**
      * The custom breakpoints for the different layout modi.
      */
     breakpoints?: LayoutBreakpoints;
 }
 /**
- * The PiralInstance component, which is an event emitter containing the React
- * functional component as well as some other utilities and helpers.
+ * The options for creating a new PiralInstance object.
+ */
+export interface PiralInstanceOptions extends PiralConfiguration {
+    /**
+     * Defines the id of this instance. Used in case of multiple instances.
+     */
+    id?: string;
+}
+/**
+ * The PiralInstance object, which is an event emitter with some other
+ * utilities and helper. This object is the source for the React
+ * functional component (`Piral`).
  */
 export interface PiralInstance extends EventEmitter {
+    /**
+     * The id of the Piral instance.
+     */
+    id: string;
     /**
      * The global state context instance.
      */

package/lib/types/layout.d.ts

@@ -1,12 +1,12 @@
 /**
  * The mapping of breakpoints to layout type index.
  */
-export declare type LayoutBreakpoints = [string, string, string];
+export type LayoutBreakpoints = [string, string, string];
 /**
  * The different known layout types.
  */
-export declare type LayoutType = 'mobile' | 'tablet' | 'desktop';
+export type LayoutType = 'mobile' | 'tablet' | 'desktop';
 /**
  * The mapping of the layout types to breakpoint index.
  */
-export declare type LayoutTypes = [LayoutType, LayoutType, LayoutType];
+export type LayoutTypes = [LayoutType, LayoutType, LayoutType];

package/lib/types/navigation.d.ts

@@ -0,0 +1,94 @@
+import type { Disposable } from './utils';
+export type NavigationAction = 'POP' | 'PUSH' | 'REPLACE';
+export interface NavigationLocation {
+    /**
+     * The fully qualified URL incl. the origin and base path.
+     */
+    href: string;
+    /**
+     * The location.pathname property is a string that contains an initial "/"
+     * followed by the remainder of the URL up to the ?.
+     */
+    pathname: string;
+    /**
+     * The location.search property is a string that contains an initial "?"
+     * followed by the key=value pairs in the query string. If there are no
+     * parameters, this value may be the empty string (i.e. '').
+     */
+    search: string;
+    /**
+     * The location.hash property is a string that contains an initial "#"
+     * followed by fragment identifier of the URL. If there is no fragment
+     * identifier, this value may be the empty string (i.e. '').
+     */
+    hash: string;
+    /**
+     * The location.state property is a user-supplied State object that is
+     * associated with this location. This can be a useful place to store
+     * any information you do not want to put in the URL, e.g. session-specific
+     * data.
+     */
+    state: unknown;
+    /**
+     * The location.key property is a unique string associated with this location.
+     * On the initial location, this will be the string default. On all subsequent
+     * locations, this string will be a unique identifier.
+     */
+    key?: string;
+}
+export interface NavigationListener {
+    (update: NavigationUpdate): void;
+}
+export interface NavigationBlocker {
+    (tx: NavigationTransition): void;
+}
+export interface NavigationUpdate {
+    action: NavigationAction;
+    location: NavigationLocation;
+}
+export interface NavigationTransition extends NavigationUpdate {
+    retry?(): void;
+}
+export interface NavigationApi {
+    /**
+     * Pushes a new location onto the history stack.
+     */
+    push(target: string, state?: any): void;
+    /**
+     * Replaces the current location with another.
+     */
+    replace(target: string, state?: any): void;
+    /**
+     * Changes the current index in the history stack by a given delta.
+     */
+    go(n: number): void;
+    /**
+     * Prevents changes to the history stack from happening.
+     * This is useful when you want to prevent the user navigating
+     * away from the current page, for example when they have some
+     * unsaved data on the current page.
+     * @param blocker The function being called with a transition request.
+     * @returns The disposable for stopping the block.
+     */
+    block(blocker: NavigationBlocker): Disposable;
+    /**
+     * Starts listening for location changes and calls the given
+     * callback with an Update when it does.
+     * @param listener The function being called when the route changes.
+     * @returns The disposable for stopping the block.
+     */
+    listen(listener: NavigationListener): Disposable;
+    /**
+     * Gets the current navigation / application path.
+     */
+    path: string;
+    /**
+     * Gets the current navigation path incl. search and hash parts.
+     */
+    url: string;
+    /**
+     * The original router behind the navigation. Don't depend on this
+     * as the implementation is router specific and may change over time.
+     */
+    router: any;
+}

package/lib/types/navigation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=navigation.js.map

package/lib/types/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/types/navigation.ts"],"names":[],"mappings":""}

package/lib/types/plugin.d.ts

@@ -1,19 +1,6 @@
+import type { PiletApiExtender } from 'piral-base';
 import type { PiletApi } from './api';
 import type { GlobalStateContext } from './state';
-import type { PiletMetadata } from '../types';
-/**
- * Shape to be used by a Pilet API extension that requires other
- * APIs or some metadata to work properly.
- */
-export interface PiletApiExtender<T> {
-    /**
-     * Extends the base API of a module with new functionality.
-     * @param api The API created by the base layer.
-     * @param target The target the API is created for.
-     * @returns The extended API.
-     */
-    (api: PiletApi, target: PiletMetadata): T;
-}
 /**
  * Shape to be used by a plugin used in the Piral instance.
  */