sample-piral 1.6.2-beta.7394 → 1.6.2-beta.7457

package/app/index.d.ts

@@ -170,6 +170,8 @@ export interface PiralEventMap extends PiralCustomEventMap {
   [custom: string]: any;
   "store-data": PiralStoreDataEvent;
   "unhandled-error": PiralUnhandledErrorEvent;
+  "loading-pilets": PiralLoadingPiletsEvent;
+  "loaded-pilets": PiralLoadedPiletsEvent;
 }
 
 export interface PiletLocaleApi {
@@ -473,6 +475,30 @@ export interface PiralUnhandledErrorEvent {
   pilet: string;
 }
 
+/**
+ * Gets fired when the loading of pilets is triggered.
+ */
+export interface PiralLoadingPiletsEvent {
+  /**
+   * The options that have been supplied for loading the pilets.
+   */
+  options: LoadPiletsOptions;
+}
+
+/**
+ * Gets fired when all pilets have been loaded.
+ */
+export interface PiralLoadedPiletsEvent {
+  /**
+   * The pilets that have been loaded.
+   */
+  pilets: Array<Pilet>;
+  /**
+   * The loading error, if any.
+   */
+  error?: Error;
+}
+
 export type AnyLocalizationMessages = LocalizationMessages | NestedLocalizationMessages;
 
 export interface LocalizationMessages {
@@ -730,6 +756,56 @@ export interface PiralChangeUserEvent {
   current: UserInfo;
 }
 
+/**
+ * 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;
+  /**
+   * Optionally, defines a set of loading hooks to be used.
+   */
+  hooks?: PiletLifecycleHooks;
+  /**
+   * 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;
+}
+
+/**
+ * An evaluated pilet, i.e., a full pilet: functionality and metadata.
+ */
+export type Pilet = SinglePilet | MultiPilet;
+
 export interface NestedLocalizationMessages {
   [lang: string]: NestedTranslations;
 }
@@ -932,6 +1008,94 @@ export interface ExtensionRegistration extends BaseRegistration {
   defaults: any;
 }
 
+/**
+ * The creator function for the pilet API.
+ */
+export interface PiletApiCreator {
+  /**
+   * Creates an API for the given raw pilet.
+   * @param target The raw (meta) content of the pilet.
+   * @returns The API object to be used with the pilet.
+   */
+  (target: PiletMetadata): PiletApi;
+}
+
+/**
+ * The interface describing a function capable of fetching pilets.
+ */
+export interface PiletRequester {
+  /**
+   * Gets the raw pilets (e.g., from a server) asynchronously.
+   */
+  (): Promise<PiletEntries>;
+}
+
+/**
+ * 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 {
+  (entry: PiletEntry): Promise<Pilet>;
+}
+
+/**
+ * Defines the spec identifiers for custom loading.
+ */
+export type CustomSpecLoaders = Record<string, PiletLoader>;
+
+/**
+ * A set of pipeline hooks used by the Piral loading orchestrator.
+ */
+export interface PiletLifecycleHooks {
+  /**
+   * Hook fired before a pilet is loaded.
+   */
+  loadPilet?(pilet: PiletMetadata): void;
+  /**
+   * Hook fired before a pilet is being set up.
+   */
+  setupPilet?(pilet: Pilet): void;
+  /**
+   * Hook fired before a pilet is being cleaned up.
+   */
+  cleanupPilet?(pilet: Pilet): void;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * An evaluated single pilet.
+ */
+export type SinglePilet = SinglePiletApp & PiletMetadata;
+
+/**
+ * An evaluated multi pilet.
+ */
+export type MultiPilet = MultiPiletApp & PiletMetadata;
+
 export interface NestedTranslations {
   [tag: string]: string | NestedTranslations;
 }
@@ -1019,6 +1183,60 @@ export interface BaseRegistration {
 
 export type WrappedComponent<TProps> = React.ComponentType<React.PropsWithChildren<Without<TProps, keyof BaseComponentProps>>>;
 
+/**
+ * The entries representing pilets from a feed service response.
+ */
+export type PiletEntries = Array<PiletEntry>;
+
+/**
+ * Pilet entry representing part of a response from the feed service.
+ */
+export type PiletEntry = MultiPiletEntry | SinglePiletEntry;
+
+/**
+ * The callback to be used when pilets have been loaded.
+ */
+export interface PiletsLoaded {
+  (error: Error | undefined, pilets: Array<Pilet>): void;
+}
+
+/**
+ * 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 referenced stylesheets to load / integrate.
+   * This would only be used by v3 pilets.
+   */
+  styles?: Array<string>;
+  /**
+   * The referenced WebAssembly binaries to load / integrate.
+   * This would only be used by v3 pilets.
+   */
+  assemblies?: Array<string>;
+}
+
+/**
+ * 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 PiralCustomMenuTypes {}
 
 export interface PiralCustomNotificationTypes {}
@@ -1073,6 +1291,16 @@ export interface NavigationApi {
 
 export type Without<T, K> = Pick<T, Exclude<keyof T, K>>;
 
+/**
+ * The metadata response for a multi pilet.
+ */
+export type MultiPiletEntry = PiletBundleEntry;
+
+/**
+ * The metadata response for a single pilet.
+ */
+export type SinglePiletEntry = PiletV0Entry | PiletV1Entry | PiletV2Entry | PiletV3Entry | PiletMfEntry | PiletVxEntry;
+
 export interface NavigationBlocker {
   (tx: NavigationTransition): void;
 }
@@ -1081,6 +1309,238 @@ export interface NavigationListener {
   (update: NavigationUpdate): void;
 }
 
+/**
+ * Metadata for pilets using the bundle schema.
+ */
+export interface PiletBundleEntry {
+  /**
+   * The name of the bundle pilet, i.e., the package id.
+   */
+  name?: string;
+  /**
+   * Optionally provides the version of the specification for this pilet.
+   */
+  spec?: "v1";
+  /**
+   * The link for retrieving the bundle content of the pilet.
+   */
+  link: string;
+  /**
+   * The reference name for the global bundle-shared require.
+   */
+  bundle: string;
+  /**
+   * The computed integrity of the pilet. Will be used to set the
+   * integrity value of the script.
+   */
+  integrity?: string;
+  /**
+   * Optionally provides some custom metadata for the pilet.
+   */
+  custom?: any;
+  /**
+   * Additional shared dependency script files.
+   */
+  dependencies?: Record<string, string>;
+}
+
+/**
+ * Metadata for pilets using the v0 schema.
+ */
+export type PiletV0Entry = PiletV0ContentEntry | PiletV0LinkEntry;
+
+/**
+ * Metadata for pilets using the v1 schema.
+ */
+export interface PiletV1Entry {
+  /**
+   * The name of the pilet, i.e., the package id.
+   */
+  name: string;
+  /**
+   * The version of the pilet. Should be semantically versioned.
+   */
+  version: string;
+  /**
+   * Optionally provides the version of the specification for this pilet.
+   */
+  spec?: "v1";
+  /**
+   * The link for retrieving the content of the pilet.
+   */
+  link: string;
+  /**
+   * The reference name for the global require.
+   */
+  requireRef: string;
+  /**
+   * The computed integrity of the pilet. Will be used to set the
+   * integrity value of the script.
+   */
+  integrity?: string;
+  /**
+   * Optionally provides some custom metadata for the pilet.
+   */
+  custom?: any;
+  /**
+   * Optionally provides some configuration to be used in the pilet.
+   */
+  config?: Record<string, any>;
+  /**
+   * Additional shared dependency script files.
+   */
+  dependencies?: Record<string, string>;
+}
+
+/**
+ * Metadata for pilets using the v2 schema.
+ */
+export interface PiletV2Entry {
+  /**
+   * The name of the pilet, i.e., the package id.
+   */
+  name: string;
+  /**
+   * The version of the pilet. Should be semantically versioned.
+   */
+  version: string;
+  /**
+   * Provides the version of the specification for this pilet.
+   */
+  spec: "v2";
+  /**
+   * The reference name for the global require.
+   */
+  requireRef: string;
+  /**
+   * The computed integrity of the pilet.
+   */
+  integrity?: string;
+  /**
+   * The link for retrieving the content of the pilet.
+   */
+  link: string;
+  /**
+   * Optionally provides some custom metadata for the pilet.
+   */
+  custom?: any;
+  /**
+   * Optionally provides some configuration to be used in the pilet.
+   */
+  config?: Record<string, any>;
+  /**
+   * Additional shared dependency script files.
+   */
+  dependencies?: Record<string, string>;
+}
+
+/**
+ * Metadata for pilets using the v3 schema.
+ */
+export interface PiletV3Entry {
+  /**
+   * The name of the pilet, i.e., the package id.
+   */
+  name: string;
+  /**
+   * The version of the pilet. Should be semantically versioned.
+   */
+  version: string;
+  /**
+   * Provides the version of the specification for this pilet.
+   */
+  spec: "v3";
+  /**
+   * The reference name for the global require.
+   */
+  requireRef: string;
+  /**
+   * The computed integrity of the pilet.
+   */
+  integrity?: string;
+  /**
+   * The fallback link for retrieving the content of the pilet.
+   */
+  link: string;
+  /**
+   * The links for specific variations of the pilet, e.g., "client", "server", ...
+   */
+  variations?: Record<string, string>;
+  /**
+   * Optionally provides some custom metadata for the pilet.
+   */
+  custom?: any;
+  /**
+   * Optionally provides some configuration to be used in the pilet.
+   */
+  config?: Record<string, any>;
+  /**
+   * Additional shared dependency script files.
+   */
+  dependencies?: Record<string, string>;
+}
+
+/**
+ * Metadata for pilets using the v2 schema.
+ */
+export interface PiletMfEntry {
+  /**
+   * The name of the pilet, i.e., the package id.
+   */
+  name: string;
+  /**
+   * The version of the pilet. Should be semantically versioned.
+   */
+  version: string;
+  /**
+   * Provides the version of the specification for this pilet.
+   */
+  spec: "mf";
+  /**
+   * The computed integrity of the pilet.
+   */
+  integrity?: string;
+  /**
+   * The fallback link for retrieving the content of the pilet.
+   */
+  link: string;
+  /**
+   * Optionally provides some custom metadata for the pilet.
+   */
+  custom?: any;
+  /**
+   * Optionally provides some configuration to be used in the pilet.
+   */
+  config?: Record<string, any>;
+}
+
+export interface PiletVxEntry {
+  /**
+   * The name of the pilet, i.e., the package id.
+   */
+  name: string;
+  /**
+   * The version of the pilet. Should be semantically versioned.
+   */
+  version: string;
+  /**
+   * Provides an identifier for the custom specification.
+   */
+  spec: string;
+  /**
+   * Optionally provides some custom metadata for the pilet.
+   */
+  custom?: any;
+  /**
+   * Optionally provides some configuration to be used in the pilet.
+   */
+  config?: Record<string, any>;
+  /**
+   * Additional shared dependency script files.
+   */
+  dependencies?: Record<string, string>;
+}
+
 export interface NavigationTransition extends NavigationUpdate {
   retry?(): void;
 }
@@ -1090,6 +1550,34 @@ export interface NavigationUpdate {
   location: NavigationLocation;
 }
 
+/**
+ * Metadata for pilets using the v0 schema with a content.
+ */
+export interface PiletV0ContentEntry extends PiletV0BaseEntry {
+  /**
+   * The content of the pilet. If the content is not available
+   * the link will be used (unless caching has been activated).
+   */
+  content: string;
+  /**
+   * If available indicates that the pilet should not be cached.
+   * In case of a string this is interpreted as the expiration time
+   * of the cache. In case of an accurate hash this should not be
+   * required or set.
+   */
+  noCache?: boolean | string;
+}
+
+/**
+ * Metadata for pilets using the v0 schema with a link.
+ */
+export interface PiletV0LinkEntry extends PiletV0BaseEntry {
+  /**
+   * The link for retrieving the content of the pilet.
+   */
+  link: string;
+}
+
 export type NavigationAction = "POP" | "PUSH" | "REPLACE";
 
 export interface NavigationLocation {
@@ -1127,4 +1615,39 @@ export interface NavigationLocation {
    * locations, this string will be a unique identifier.
    */
   key?: string;
+}
+
+/**
+ * Basic metadata for pilets using the v0 schema.
+ */
+export interface PiletV0BaseEntry {
+  /**
+   * The name of the pilet, i.e., the package id.
+   */
+  name: string;
+  /**
+   * The version of the pilet. Should be semantically versioned.
+   */
+  version: string;
+  /**
+   * Optionally provides the version of the specification for this pilet.
+   */
+  spec?: "v0";
+  /**
+   * The computed hash value of the pilet's content. Should be
+   * accurate to allow caching.
+   */
+  hash: string;
+  /**
+   * Optionally provides some custom metadata for the pilet.
+   */
+  custom?: any;
+  /**
+   * Optionally provides some configuration to be used in the pilet.
+   */
+  config?: Record<string, any>;
+  /**
+   * Additional shared dependency script files.
+   */
+  dependencies?: Record<string, string>;
 }

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.282bb1.js"></script></head>
+<script defer src="/index.2f9975.js"></script></head>
 <body>
 <div id="app">
   <div class="pi-center">

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sample-piral",
   "description": "Example project illustrating the use of the piral and piral-cli packages.",
-  "version": "1.6.2-beta.7394",
+  "version": "1.6.2-beta.7457",
   "license": "MIT",
   "homepage": "https://piral.io",
   "keywords": [
@@ -31,7 +31,7 @@
     "files": []
   },
   "piralCLI": {
-    "version": "1.6.2-beta.7394",
+    "version": "1.6.2-beta.7457",
     "generated": true
   },
   "main": "./app/index.js",
@@ -44,14 +44,14 @@
     "@types/react-dom": "^18.0.0",
     "@types/react-router": "^5.1.8",
     "@types/react-router-dom": "^5.1.6",
-    "piral-cli": "^1.6.2-beta.7394",
-    "piral-cli-webpack5": "^1.6.2-beta.7394",
+    "piral-cli": "^1.6.2-beta.7457",
+    "piral-cli-webpack5": "^1.6.2-beta.7457",
     "sass": "^1.17.0",
     "bootstrap": "^4.3.1",
-    "piral": "^1.6.2-beta.7394",
-    "piral-auth": "^1.6.2-beta.7394",
-    "piral-hooks-utils": "^1.6.2-beta.7394",
-    "piral-search": "^1.6.2-beta.7394",
+    "piral": "^1.6.2-beta.7457",
+    "piral-auth": "^1.6.2-beta.7457",
+    "piral-hooks-utils": "^1.6.2-beta.7457",
+    "piral-search": "^1.6.2-beta.7457",
     "reactstrap": "8.10.1",
     "tslib": "2.5.2",
     "react": "18.2.0",