sample-piral 0.14.4 → 0.14.5-beta.3339

package/app/index.d.ts

@@ -964,6 +964,7 @@ declare module "sample-piral" {
   export interface ComponentContext {
     router: ReactRouter.RouteComponentProps;
     state: LibreAtom.Atom<GlobalState>;
+    readState: PiralActions["readState"];
   }
 
   /**
@@ -1043,6 +1044,138 @@ declare module "sample-piral" {
     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.
    */
@@ -1104,6 +1237,10 @@ declare module "sample-piral" {
      * Gets an unrecoverable application error, if any.
      */
     error: Error | undefined;
+    /**
+     * Gets the public path of the application.
+     */
+    publicPath: string;
   }
 
   export type ErrorComponentsState = {
@@ -1178,6 +1315,199 @@ declare module "sample-piral" {
     expires: number;
   }
 
+  /**
+   * Custom actions defined outside of piral-core.
+   */
+  export interface PiralCustomActions {
+    /**
+     * Changes the selected language.
+     * @param selected The selected language.
+     */
+    selectLanguage(selected: string): void;
+    /**
+     * Gets the translation for the given key at the current
+     * language.
+     */
+    translate(tag: string, variables?: Record<string, string>): string;
+    /**
+     * Sets the translations (both global and local) for
+     * the given language.
+     * @param language The language to set the translations for.
+     * @param data The global and local translations.
+     */
+    setTranslations(language: string, data: LanguageData): void;
+    /**
+     * Gets the translations (both global and local) for
+     * the given language.
+     * @param language The language to get the translations for.
+     * @result The global and local translations.
+     */
+    getTranslations(language: string): LanguageData;
+    /**
+     * 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;
+    /**
+     * Registers a new menu item.
+     * @param name The name of the menu item.
+     * @param value The menu registration.
+     */
+    registerMenuItem(name: string, value: MenuItemRegistration): void;
+    /**
+     * Unregisters an existing menu item.
+     * @param name The name of the menu item to be removed.
+     */
+    unregisterMenuItem(name: string): void;
+    /**
+     * Opens the given notification.
+     * @param notification The notification to show.
+     */
+    openNotification(notification: OpenNotification): void;
+    /**
+     * Closes the given notification.
+     * @param notification The notification to hide.
+     */
+    closeNotification(notification: OpenNotification): void;
+    /**
+     * Opens the provided dialog.
+     * @param dialog The dialog to show.
+     */
+    openModal(dialog: OpenModalDialog): void;
+    /**
+     * Closes the provided dialog.
+     * @param dialog The dialog to hide.
+     */
+    closeModal(dialog: OpenModalDialog): void;
+    /**
+     * Registers a new modal dialog.
+     * @param name The name of the modal.
+     * @param value The modal registration.
+     */
+    registerModal(name: string, value: ModalRegistration): void;
+    /**
+     * Unregisters an existing modal dialog.
+     * @param name The name of the modal to be removed.
+     */
+    unregisterModal(name: string): void;
+    /**
+     * Creates a new (empty) feed.
+     * @param id The id of the feed.
+     */
+    createFeed(id: string): void;
+    /**
+     * Destroys an existing feed.
+     * @param id The id of the feed.
+     */
+    destroyFeed(id: string): void;
+    /**
+     * Loads the feed via the provided details.
+     * @param feed The feed details to use for loading.
+     */
+    loadFeed<TData, TItem>(feed: ConnectorDetails<TData, TItem>): void;
+    /**
+     * Updates an existing feed.
+     * @param id The id of the feed.
+     * @param item The item to pass on to the reducer.
+     * @param reducer The reducer to use.
+     */
+    updateFeed<TData, TItem>(id: string, item: TItem, reducer: FeedReducer<TData, TItem>): void;
+    /**
+     * Registers a new search provider.
+     * @param name The name of the search provider.
+     * @param value The value representing the provider.
+     */
+    registerSearchProvider(name: string, value: SearchProviderRegistration): void;
+    /**
+     * Unregisters an existing search provider.
+     * @param name The name of the search provider.
+     */
+    unregisterSearchProvider(name: string): void;
+    /**
+     * Sets the current search input.
+     * @param input The input to set.
+     */
+    setSearchInput(input: string): void;
+    /**
+     * Resets the search results.
+     * @param input The input to set.
+     * @param loading Determines if further results are currently loading.
+     */
+    resetSearchResults(input: string, loading: boolean): void;
+    /**
+     * Appends more results to the existing results.
+     * @param items The items to append.
+     * @param done Determines if more results are pending.
+     */
+    appendSearchResults(items: Array<React.ReactChild>, done: boolean): void;
+    /**
+     * Prepends more results to the existing results.
+     * @param items The items to prepend.
+     * @param done Determines if more results are pending.
+     */
+    prependSearchResults(items: Array<React.ReactChild>, done: boolean): void;
+    /**
+     * Triggers the search explicitly.
+     * @param input Optionally sets the query to look for. Otherwise the current input is taken.
+     * @param immediate Optionally, determins if the search was invoked immediately.
+     */
+    triggerSearch(input?: string, immediate?: boolean): Disposable;
+    /**
+     * Sets the currently logged in user.
+     * @param user The current user or undefined is anonymous.
+     * @param features The features for the current user, if any.
+     * @param permissions The permissions of the current user, if any.
+     */
+    setUser(user: UserInfo, features: UserFeatures, permissions: UserPermissions): 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;
+  }
+
   export interface OpenNotification {
     id: string;
     component: React.ComponentType<BareNotificationProps>;
@@ -1232,11 +1562,6 @@ declare module "sample-piral" {
     };
   }
 
-  /**
-   * The different known layout types.
-   */
-  export type LayoutType = "mobile" | "tablet" | "desktop";
-
   /**
    * Map of all error types to their respective props.
    */
@@ -1364,23 +1689,90 @@ declare module "sample-piral" {
     searchProviders: Dict<SearchProviderRegistration>;
   }
 
+  export interface LanguageData {
+    global: Translations;
+    locals: Array<{
+      name: string;
+      value: Translations;
+    }>;
+  }
+
+  export interface TileRegistration extends BaseRegistration {
+    component: WrappedComponent<TileComponentProps>;
+    preferences: TilePreferences;
+  }
+
+  export interface MenuItemRegistration extends BaseRegistration {
+    component: WrappedComponent<MenuComponentProps>;
+    settings: MenuSettings;
+  }
+
+  export interface ModalRegistration extends BaseRegistration {
+    name: string;
+    component: WrappedComponent<ModalComponentProps<any>>;
+    defaults: any;
+  }
+
+  export interface ConnectorDetails<TData, TItem, TReducers extends FeedConnectorReducers<TData> = {}> extends FeedConnectorOptions<TData, TItem, TReducers> {
+    /**
+     * The ID of the connector.
+     */
+    id: string;
+    /**
+     * The dispose function if active.
+     */
+    dispose?(): void;
+  }
+
+  export interface SearchProviderRegistration extends BaseRegistration {
+    search: SearchHandler;
+    cancel(): void;
+    clear(): void;
+    onlyImmediate: boolean;
+  }
+
   /**
-   * 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>>;
+
   export interface FeedDataState {
     /**
      * Determines if the feed data is currently loading.
@@ -1561,37 +1953,86 @@ declare module "sample-piral" {
     [K in keyof T]: T[K];
   }[keyof T];
 
-  export interface TileRegistration extends BaseRegistration {
-    component: WrappedComponent<TileComponentProps>;
-    preferences: TilePreferences;
+  export interface SearchHandler {
+    (options: SearchOptions): Promise<Array<React.ReactChild>>;
   }
 
-  export interface MenuItemRegistration extends BaseRegistration {
-    component: WrappedComponent<MenuComponentProps>;
-    settings: MenuSettings;
+  /**
+   * 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;
   }
 
-  export interface ModalRegistration extends BaseRegistration {
-    name: string;
-    component: WrappedComponent<ModalComponentProps<any>>;
-    defaults: any;
+  /**
+   * The pilet app, i.e., the functional exports.
+   */
+  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 interface SearchProviderRegistration extends BaseRegistration {
-    search: SearchHandler;
-    cancel(): void;
-    clear(): void;
-    onlyImmediate: boolean;
+  /**
+   * Represents the dictionary of the loaded pilets and their APIs.
+   */
+  export interface PiletsBag {
+    [name: string]: PiletApi;
   }
 
   /**
-   * The base type for pilet component registration in the global state context.
+   * The options for loading pilets.
    */
-  export interface BaseRegistration {
-    pilet: string;
+  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 WrappedComponent<TProps> = React.ComponentType<Without<TProps, keyof BaseComponentProps>>;
+  export type Without<T, K> = Pick<T, Exclude<keyof T, K>>;
 
   export interface TileErrorInfoProps {
     /**
@@ -1662,9 +2103,62 @@ declare module "sample-piral" {
     error: any;
   }
 
-  export interface SearchHandler {
-    (options: SearchOptions): Promise<Array<React.ReactChild>>;
+  /**
+   * The creator function for the pilet API.
+   */
+  export interface PiletApiCreator {
+    (target: PiletMetadata): PiletApi;
   }
 
-  export type Without<T, K> = Pick<T, Exclude<keyof T, K>>;
+  /**
+   * 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>Piral Sample</title>
   <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
   
-<script defer src="/index.1449bd.js"></script></head>
+<script defer src="/index.a7f28d.js"></script></head>
 <body>
 <div id="app">
   <div class="pi-center">

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.1449bd.js');
+    require('.//index.a7f28d.js');
     const ctx = window['dbg:piral'];
     const dependencies = (ctx && ctx.pilets && ctx.pilets.getDependencies({})) || {};
     module.exports = dependencies['sample-piral'] || {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sample-piral",
   "description": "Example project illustrating the use of the piral and piral-cli packages.",
-  "version": "0.14.4",
+  "version": "0.14.5-beta.3339",
   "license": "MIT",
   "homepage": "https://piral.io",
   "keywords": [