sample-cross-fx 0.14.5-beta.3336 → 0.14.5-beta.3347

package/app/index.d.ts

@@ -1200,6 +1200,7 @@ declare module "sample-cross-fx" {
   export interface ComponentContext {
     router: ReactRouter.RouteComponentProps;
     state: LibreAtom.Atom<GlobalState>;
+    readState: PiralActions["readState"];
   }
 
   /**
@@ -1279,6 +1280,138 @@ declare module "sample-cross-fx" {
     provider?: React.ComponentType;
   }
 
+  /**
+   * The globally defined actions.
+   */
+  export interface PiralActions extends PiralCustomActions {
+    /**
+     * Initializes the application shell.
+     * @param loading The current loading state.
+     * @param error The application error, if any.
+     * @param modules The loaded pilets.
+     */
+    initialize(loading: boolean, error: Error | undefined, modules: Array<Pilet>): void;
+    /**
+     * Injects a pilet at runtime - removes the pilet from registry first if available.
+     * @param pilet The pilet to be injected.
+     */
+    injectPilet(pilet: Pilet): void;
+    /**
+     * Defines a single action for Piral.
+     * @param actionName The name of the action to define.
+     * @param action The action to include.
+     */
+    defineAction<T extends keyof PiralActions>(actionName: T, action: PiralAction<PiralActions[T]>): void;
+    /**
+     * Defines a set of actions for Piral.
+     * @param actions The actions to define.
+     */
+    defineActions(actions: PiralDefineActions): void;
+    /**
+     * Reads the value of a shared data item.
+     * @param name The name of the shared item.
+     */
+    readDataValue(name: string): any;
+    /**
+     * Tries to write a shared data item. The write access is only
+     * possible if the name belongs to the provided owner or has not
+     * been taken yet.
+     * Setting the value to null will release it.
+     * @param name The name of the shared data item.
+     * @param value The value of the shared data item.
+     * @param owner The owner of the shared data item.
+     * @param target The target storage locatation.
+     * @param expiration The time for when to dispose the shared item.
+     */
+    tryWriteDataItem(name: string, value: any, owner: string, target: DataStoreTarget, expiration: number): boolean;
+    /**
+     * Performs a layout change.
+     * @param current The layout to take.
+     */
+    changeLayout(current: LayoutType): void;
+    /**
+     * Registers a new route to be resolved.
+     * @param route The route to register.
+     * @param value The page to be rendered on the route.
+     */
+    registerPage(route: string, value: PageRegistration): void;
+    /**
+     * Unregisters an existing route.
+     * @param route The route to be removed.
+     */
+    unregisterPage(route: string): void;
+    /**
+     * Registers a new extension.
+     * @param name The name of the extension category.
+     * @param value The extension registration.
+     */
+    registerExtension(name: string, value: ExtensionRegistration): void;
+    /**
+     * Unregisters an existing extension.
+     * @param name The name of the extension category.
+     * @param value The extension that will be removed.
+     */
+    unregisterExtension(name: string, reference: any): void;
+    /**
+     * Sets the common component to render.
+     * @param name The name of the component.
+     * @param component The component to use for rendering.
+     */
+    setComponent<TKey extends keyof ComponentsState>(name: TKey, component: ComponentsState[TKey]): void;
+    /**
+     * Sets the error component to render.
+     * @param type The type of the error.
+     * @param component The component to use for rendering.
+     */
+    setErrorComponent<TKey extends keyof ErrorComponentsState>(type: TKey, component: ErrorComponentsState[TKey]): void;
+    /**
+     * Sets the common routes to render.
+     * @param path The name of the component.
+     * @param component The component to use for rendering.
+     */
+    setRoute<T = {}>(path: string, component: React.ComponentType<ReactRouter.RouteComponentProps<T>>): void;
+    /**
+     * Includes a new provider as a sub-provider to the current provider.
+     * @param provider The provider to include.
+     */
+    includeProvider(provider: JSX.Element): void;
+    /**
+     * Destroys (i.e., resets) the given portal instance.
+     * @param id The id of the portal to destroy.
+     */
+    destroyPortal(id: string): void;
+    /**
+     * Includes the provided portal in the rendering pipeline.
+     * @param id The id of the portal to use.
+     * @param entry The child to render.
+     */
+    showPortal(id: string, entry: React.ReactPortal): void;
+    /**
+     * Hides the provided portal in the rendering pipeline.
+     * @param id The id of the portal to use.
+     * @param entry The child to remove.
+     */
+    hidePortal(id: string, entry: React.ReactPortal): void;
+    /**
+     * Updates the provided portal in the rendering pipeline.
+     * @param id The id of the portal to use.
+     * @param current The currently displayed child.
+     * @param next The updated child that should be displayed.
+     */
+    updatePortal(id: string, current: React.ReactPortal, next: React.ReactPortal): void;
+    /**
+     * Dispatches a state change.
+     * @param update The update function creating a new state.
+     */
+    dispatch(update: (state: GlobalState) => GlobalState): void;
+    /**
+     * Reads the selected part of the global state.
+     * @param select The selector for getting the desired part.
+     * @returns The desired part.
+     */
+    readState<S>(select: (state: GlobalState) => S): S;
+  }
+
   /**
    * Custom state extensions defined outside of piral-core.
    */
@@ -1302,6 +1435,10 @@ declare module "sample-cross-fx" {
      * Gets an unrecoverable application error, if any.
      */
     error: Error | undefined;
+    /**
+     * Gets the public path of the application.
+     */
+    publicPath: string;
   }
 
   export type ErrorComponentsState = {
@@ -1376,11 +1513,64 @@ declare module "sample-cross-fx" {
     expires: number;
   }
 
+  /**
+   * Custom actions defined outside of piral-core.
+   */
+  export interface PiralCustomActions {
+    /**
+     * Registers a new tile.
+     * @param name The name of the tile.
+     * @param value The tile registration.
+     */
+    registerTile(name: string, value: TileRegistration): void;
+    /**
+     * Unregisters an existing tile.
+     * @param name The name of the tile to be removed.
+     */
+    unregisterTile(name: string): void;
+  }
+
+  /**
+   * An evaluated pilet, i.e., a full pilet: functionality and metadata.
+   */
+  export type Pilet = SinglePilet | MultiPilet;
+
+  /**
+   * The shape of an app action in Piral.
+   */
+  export interface PiralAction<T extends (...args: any) => any> {
+    (ctx: GlobalStateContext, ...args: Parameters<T>): ReturnType<T>;
+  }
+
+  /**
+   * A subset of the available app actions in Piral.
+   */
+  export type PiralDefineActions = Partial<{
+    [P in keyof PiralActions]: PiralAction<PiralActions[P]>;
+  }>;
+
   /**
    * The different known layout types.
    */
   export type LayoutType = "mobile" | "tablet" | "desktop";
 
+  /**
+   * The interface modeling the registration of a pilet page component.
+   */
+  export interface PageRegistration extends BaseRegistration {
+    component: WrappedComponent<PageComponentProps>;
+    meta: PiralPageMeta;
+  }
+
+  /**
+   * The interface modeling the registration of a pilet extension component.
+   */
+  export interface ExtensionRegistration extends BaseRegistration {
+    component: WrappedComponent<ExtensionComponentProps<string>>;
+    reference: any;
+    defaults: any;
+  }
+
   /**
    * Map of all error types to their respective props.
    */
@@ -1456,23 +1646,53 @@ declare module "sample-cross-fx" {
     tiles: Dict<TileRegistration>;
   }
 
+  export interface TileRegistration extends BaseRegistration {
+    component: WrappedComponent<TileComponentProps>;
+    preferences: TilePreferences;
+  }
+
   /**
-   * The interface modeling the registration of a pilet page component.
+   * An evaluated single pilet.
    */
-  export interface PageRegistration extends BaseRegistration {
-    component: WrappedComponent<PageComponentProps>;
-    meta: PiralPageMeta;
+  export type SinglePilet = SinglePiletApp & SinglePiletMetadata;
+
+  /**
+   * An evaluated multi pilet.
+   */
+  export type MultiPilet = MultiPiletApp & MultiPiletMetadata;
+
+  /**
+   * The Piral app instance context.
+   */
+  export interface GlobalStateContext extends PiralActions, EventEmitter {
+    /**
+     * The global state context atom.
+     * Changes to the state should always be dispatched via the `dispatch` action.
+     */
+    state: LibreAtom.Atom<GlobalState>;
+    /**
+     * The API objects created for the loaded pilets.
+     */
+    apis: PiletsBag;
+    /**
+     * The available component converters.
+     */
+    converters: ComponentConverters<any>;
+    /**
+     * The initial options.
+     */
+    options: LoadPiletsOptions;
   }
 
   /**
-   * The interface modeling the registration of a pilet extension component.
+   * The base type for pilet component registration in the global state context.
    */
-  export interface ExtensionRegistration extends BaseRegistration {
-    component: WrappedComponent<ExtensionComponentProps<string>>;
-    reference: any;
-    defaults: any;
+  export interface BaseRegistration {
+    pilet: string;
   }
 
+  export type WrappedComponent<TProps> = React.ComponentType<Without<TProps, keyof BaseComponentProps>>;
+
   /**
    * Custom errors defined outside of piral-core.
    */
@@ -1571,19 +1791,82 @@ declare module "sample-cross-fx" {
     [K in keyof T]: T[K];
   }[keyof T];
 
-  export interface TileRegistration extends BaseRegistration {
-    component: WrappedComponent<TileComponentProps>;
-    preferences: TilePreferences;
+  /**
+   * The pilet app, i.e., the functional exports.
+   */
+  export interface SinglePiletApp {
+    /**
+     * Integrates the evaluated pilet into the application.
+     * @param api The API to access the application.
+     */
+    setup(api: PiletApi): void | Promise<void>;
+    /**
+     * Optional function for cleanup.
+     * @param api The API to access the application.
+     */
+    teardown?(api: PiletApi): void;
   }
 
   /**
-   * The base type for pilet component registration in the global state context.
+   * The pilet app, i.e., the functional exports.
    */
-  export interface BaseRegistration {
-    pilet: string;
+  export interface MultiPiletApp {
+    /**
+     * Integrates the evaluated pilet into the application.
+     * @param api The API to access the application.
+     */
+    setup(apiFactory: PiletApiCreator): void | Promise<void>;
   }
 
-  export type WrappedComponent<TProps> = React.ComponentType<Without<TProps, keyof BaseComponentProps>>;
+  /**
+   * Represents the dictionary of the loaded pilets and their APIs.
+   */
+  export interface PiletsBag {
+    [name: string]: PiletApi;
+  }
+
+  /**
+   * The options for loading pilets.
+   */
+  export interface LoadPiletsOptions {
+    /**
+     * The callback function for creating an API object.
+     * The API object is passed on to a specific pilet.
+     */
+    createApi: PiletApiCreator;
+    /**
+     * The callback for fetching the dynamic pilets.
+     */
+    fetchPilets: PiletRequester;
+    /**
+     * Optionally, some already existing evaluated pilets, e.g.,
+     * helpful when debugging or in SSR scenarios.
+     */
+    pilets?: Array<Pilet>;
+    /**
+     * Optionally, configures the default loader.
+     */
+    config?: DefaultLoaderConfig;
+    /**
+     * Optionally, defines the default way how to load a pilet.
+     */
+    loadPilet?: PiletLoader;
+    /**
+     * Optionally, defines loaders for custom specifications.
+     */
+    loaders?: CustomSpecLoaders;
+    /**
+     * Gets the map of globally available dependencies with their names
+     * as keys and their evaluated pilet content as value.
+     */
+    dependencies?: AvailableDependencies;
+    /**
+     * Optionally, defines the loading strategy to use.
+     */
+    strategy?: PiletLoadingStrategy;
+  }
+
+  export type Without<T, K> = Pick<T, Exclude<keyof T, K>>;
 
   export interface TileErrorInfoProps {
     /**
@@ -1604,5 +1887,62 @@ declare module "sample-cross-fx" {
     rows: number;
   }
 
-  export type Without<T, K> = Pick<T, Exclude<keyof T, K>>;
+  /**
+   * The creator function for the pilet API.
+   */
+  export interface PiletApiCreator {
+    (target: PiletMetadata): PiletApi;
+  }
+
+  /**
+   * The interface describing a function capable of fetching pilets.
+   */
+  export interface PiletRequester {
+    (): Promise<Array<PiletMetadata>>;
+  }
+
+  /**
+   * Additional configuration options for the default loader.
+   */
+  export interface DefaultLoaderConfig {
+    /**
+     * Sets the cross-origin attribute of potential script tags.
+     * For pilets v1 this may be useful. Otherwise, only pilets that
+     * have an integrity defined will be set to "anonymous".
+     */
+    crossOrigin?: string;
+  }
+
+  /**
+   * The callback to be used to load a single pilet.
+   */
+  export interface PiletLoader {
+    (meta: PiletMetadata): Promise<Pilet>;
+  }
+
+  /**
+   * Defines the spec identifiers for custom loading.
+   */
+  export type CustomSpecLoaders = Record<string, PiletLoader>;
+
+  /**
+   * The record containing all available dependencies.
+   */
+  export interface AvailableDependencies {
+    [name: string]: any;
+  }
+
+  /**
+   * The strategy for how pilets are loaded at runtime.
+   */
+  export interface PiletLoadingStrategy {
+    (options: LoadPiletsOptions, pilets: PiletsLoaded): PromiseLike<void>;
+  }
+
+  /**
+   * The callback to be used when pilets have been loaded.
+   */
+  export interface PiletsLoaded {
+    (error: Error | undefined, pilets: Array<Pilet>): void;
+  }
 }

package/app/index.html

@@ -5,7 +5,7 @@
   <title>Sample - Cross Framework with Piral</title>
   <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
   
-<script defer src="/index.7f31c7.js"></script></head>
+<script defer src="/index.201640.js"></script></head>
 <body>
 <div id="app"></div>
 

package/app/index.js

@@ -2,7 +2,7 @@ if (process.env.NODE_ENV === 'test') {
   // behavior for the test environment, we'll try to make it work
 
   if (typeof window !== 'undefined') {
-    require('.//index.7f31c7.js');
+    require('.//index.201640.js');
     const ctx = window['dbg:piral'];
     const dependencies = (ctx && ctx.pilets && ctx.pilets.getDependencies({})) || {};
     module.exports = dependencies['sample-cross-fx'] || {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sample-cross-fx",
   "description": "Example project illustrating the mixing of different (opt-in) frameworks via plugins.",
-  "version": "0.14.5-beta.3336",
+  "version": "0.14.5-beta.3347",
   "license": "MIT",
   "homepage": "https://piral.io",
   "keywords": [