piral-core 1.0.0-pre.2217 → 1.0.0

package/src/tools/debugger.ts

@@ -0,0 +1,84 @@
+import { LoadPiletsOptions } from 'piral-base';
+import { installPiralDebug, DebuggerExtensionOptions } from 'piral-debug-utils';
+import { GlobalStateContext } from '../types';
+
+export function integrateDebugger(
+  context: GlobalStateContext,
+  options: LoadPiletsOptions,
+  debug: DebuggerExtensionOptions = {},
+) {
+  installPiralDebug({
+    ...debug,
+    addPilet: context.addPilet,
+    removePilet: context.removePilet,
+    updatePilet(pilet) {
+      if (!pilet.disabled) {
+        const { createApi } = options;
+        const newApi = createApi(pilet);
+
+        try {
+          context.injectPilet(pilet);
+          pilet.setup(newApi);
+        } catch (error) {
+          console.error(error);
+        }
+      } else {
+        context.injectPilet(pilet);
+      }
+    },
+    fireEvent: context.emit,
+    getDependencies() {
+      return Object.keys(options.dependencies);
+    },
+    getExtensions() {
+      return context.readState((s) => Object.keys(s.registry.extensions));
+    },
+    getRoutes() {
+      const registeredRoutes = context.readState((state) => Object.keys(state.registry.pages));
+      const componentRoutes = context.readState((state) => Object.keys(state.routes));
+      return [...componentRoutes, ...registeredRoutes];
+    },
+    getGlobalState() {
+      return context.readState((s) => s);
+    },
+    navigate(path, state) {
+      return context.navigation.push(path, state);
+    },
+    getPilets() {
+      return context.readState((s) => s.modules);
+    },
+    integrate(dbg) {
+      context.dispatch((s) => ({
+        ...s,
+        components: {
+          ...s.components,
+          ...dbg.components,
+        },
+        routes: {
+          ...s.routes,
+          ...dbg.routes,
+        },
+        registry: {
+          ...s.registry,
+          wrappers: {
+            ...s.registry.wrappers,
+            ...dbg.wrappers,
+          },
+        },
+      }));
+
+      context.state.subscribe((current, previous) => {
+        const pilets = current.modules !== previous.modules;
+        const pages = current.registry.pages !== previous.registry.pages || current.routes !== previous.routes;
+        const extensions = current.registry.extensions !== previous.registry.extensions;
+        const state = current !== previous;
+        dbg.onChange(previous, current, {
+          pilets,
+          pages,
+          extensions,
+          state,
+        });
+      });
+    },
+  });
+}

package/src/tools/emulator.ts

@@ -0,0 +1,13 @@
+import { LoadPiletsOptions } from 'piral-base';
+import { installPiletEmulator } from 'piral-debug-utils';
+import { GlobalStateContext } from '../types';
+
+export function integrateEmulator(context: GlobalStateContext, options: LoadPiletsOptions) {
+  installPiletEmulator(options.fetchPilets, {
+    addPilet: context.addPilet,
+    removePilet: context.removePilet,
+    integrate(requester) {
+      options.fetchPilets = requester;
+    },
+  });
+}

package/src/types/api.ts

@@ -1,12 +1,23 @@
-import type { ReactElement } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 import type { RouteComponentProps } from 'react-router';
-import type { PiletApi, Pilet, PiletMetadata, EventEmitter, SinglePilet, MultiPilet } from 'piral-base';
+import type {
+  PiletApi,
+  Pilet,
+  PiletEntry,
+  PiletEntries,
+  PiletMetadata,
+  EventEmitter,
+  PiletLoader,
+  PiletLoadingStrategy,
+} from 'piral-base';
+import type {} from 'piral-debug-utils';
 import type { PiletCustomApi, PiralCustomPageMeta } from './custom';
 import type { AnyComponent } from './components';
-import type { ExtensionSlotProps, PiralExtensionSlotMap } from './extension';
+import type { ExtensionParams, ExtensionSlotProps, PiralExtensionSlotMap } from './extension';
 import type { SharedData, DataStoreOptions } from './data';
+import type { Disposable } from './utils';
 
-export { PiletApi, Pilet, PiletMetadata, EventEmitter, SinglePilet, MultiPilet };
+export { PiletApi, Pilet, PiletMetadata, EventEmitter, PiletEntry, PiletEntries, PiletLoader, PiletLoadingStrategy };
 
 /**
  * The props that every registered component obtains.
@@ -36,25 +47,52 @@ export interface ExtensionComponentProps<T> extends BaseComponentProps {
    * The provided parameters for showing the extension.
    */
   params: T extends keyof PiralExtensionSlotMap ? PiralExtensionSlotMap[T] : T extends string ? any : T;
+  /**
+   * The optional children to receive, if any.
+   */
+  children?: ReactNode;
 }
 
+/**
+ * The meta data registered for a page.
+ */
+export interface PiralPageMeta extends PiralCustomPageMeta {}
+
 /**
  * The props that every registered page component obtains.
  */
-export interface RouteBaseProps<UrlParams = any, UrlState = any>
+export interface RouteBaseProps<UrlParams extends { [K in keyof UrlParams]?: string } = {}, UrlState = any>
   extends RouteComponentProps<UrlParams, {}, UrlState>,
     BaseComponentProps {}
 
 /**
  * The props used by a page component.
  */
-export interface PageComponentProps<T = any, S = any> extends RouteBaseProps<T, S> {}
+export interface PageComponentProps<T extends { [K in keyof T]?: string } = {}, S = any> extends RouteBaseProps<T, S> {
+  /**
+   * The meta data registered with the page.
+   */
+  meta: PiralPageMeta;
+  /**
+   * The children of the page.
+   */
+  children: ReactNode;
+}
 
 /**
  * The meta data registered for a page.
  */
 export interface PiralPageMeta extends PiralCustomPageMeta {}
 
+/**
+ * Shorthand for the definition of an extension component.
+ */
+export type AnyExtensionComponent<TName> = TName extends keyof PiralExtensionSlotMap
+  ? AnyComponent<ExtensionComponentProps<TName>>
+  : TName extends string
+  ? AnyComponent<ExtensionComponentProps<any>>
+  : AnyComponent<ExtensionComponentProps<TName>>;
+
 /**
  * Defines the Pilet API from piral-core.
  * This interface will be consumed by pilet developers so that their pilet can interact with the piral instance.
@@ -97,8 +135,8 @@ export interface PiletCoreApi {
    */
   registerExtension<TName>(
     name: TName extends string ? TName : string,
-    Component: AnyComponent<ExtensionComponentProps<TName>>,
-    defaults?: TName,
+    Component: AnyExtensionComponent<TName>,
+    defaults?: Partial<ExtensionParams<TName>>,
   ): RegistrationDisposer;
   /**
    * Unregisters a global extension component.
@@ -108,7 +146,7 @@ export interface PiletCoreApi {
    */
   unregisterExtension<TName>(
     name: TName extends string ? TName : string,
-    Component: AnyComponent<ExtensionComponentProps<TName>>,
+    Component: AnyExtensionComponent<TName>,
   ): void;
   /**
    * React component for displaying extensions for a given name.
@@ -120,11 +158,12 @@ export interface PiletCoreApi {
    * Renders an extension in a plain DOM component.
    * @param element The DOM element or shadow root as a container for rendering the extension.
    * @param props The extension's rendering props.
+   * @return The disposer to clear the extension.
    */
-  renderHtmlExtension<TName>(element: HTMLElement | ShadowRoot, props: ExtensionSlotProps<TName>): void;
+  renderHtmlExtension<TName>(element: HTMLElement | ShadowRoot, props: ExtensionSlotProps<TName>): Disposable;
 }
 
-declare module 'piral-base/lib/types' {
+declare module 'piral-base/lib/types/runtime' {
   interface PiletApi extends PiletCustomApi, PiletCoreApi {}
 }
 

package/src/types/components.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';
 
 /**
@@ -33,7 +34,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;
 }
 
 /**
@@ -45,20 +58,23 @@ 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;
 }
 
 /**
@@ -88,6 +104,10 @@ export interface PageErrorInfoProps extends RouteComponentProps {
    * The provided error details.
    */
   error: any;
+  /**
+   * The name of the pilet emitting the error.
+   */
+  pilet?: string;
 }
 
 /**
@@ -116,6 +136,10 @@ export interface ExtensionErrorInfoProps {
    * The provided error details.
    */
   error: any;
+  /**
+   * The name of the pilet emitting the error.
+   */
+  pilet?: string;
 }
 
 /**
@@ -130,6 +154,10 @@ export interface UnknownErrorInfoProps {
    * The provided error details.
    */
   error: any;
+  /**
+   * The name of the pilet emitting the error.
+   */
+  pilet?: string;
 }
 
 /**
@@ -176,9 +204,50 @@ 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 {}
+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/src/types/config.ts

@@ -1,7 +1,5 @@
 import type {
   PiletRequester,
-  PiletDependencyFetcher,
-  PiletDependencyGetter,
   PiletLoadingStrategy,
   PiletLoader,
   Pilet,
@@ -10,24 +8,30 @@ import type {
   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 🚚.
    */
@@ -44,6 +48,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.
@@ -55,12 +63,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.
    */
@@ -95,6 +97,10 @@ export interface PiralStateConfiguration {
    * Optionally, sets up some initial custom actions ⚡️.
    */
   actions?: PiralDefineActions;
+  /**
+   * Optionally, sets up additional configuration for the debug tooling 🤖.
+   */
+  debug?: DebuggerExtensionOptions;
 }
 
 /**

package/src/types/extension.ts

@@ -1,4 +1,6 @@
+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 +11,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.
    */
@@ -29,10 +53,19 @@ 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 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/src/types/index.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/src/types/instance.ts

@@ -1,15 +1,24 @@
+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.
    */
@@ -17,10 +26,25 @@ export interface PortalProps {
 }
 
 /**
- * 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/src/types/navigation.ts

@@ -0,0 +1,101 @@
+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;
+}