piral-core 1.0.0-pre.2217 → 1.0.0

package/src/types/plugin.ts

@@ -1,20 +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.

package/src/types/state.ts

@@ -1,9 +1,9 @@
-import type { ComponentType, ReactPortal } from 'react';
+import type { ComponentType, ReactPortal, PropsWithChildren } from 'react';
 import type { RouteComponentProps } from 'react-router';
-import type { Atom } from '@dbeining/react-atom';
 import type { LoadPiletsOptions } from 'piral-base';
+import type { UseBoundStore } from 'zustand';
 import type { Dict, Without } from './common';
-import type { LayoutType } from './layout';
+import type { NavigationApi } from './navigation';
 import type { SharedDataItem, DataStoreTarget } from './data';
 import type {
   PiralCustomActions,
@@ -12,7 +12,6 @@ import type {
   PiralCustomComponentsState,
 } from './custom';
 import type {
-  PiletMetadata,
   EventEmitter,
   Pilet,
   BaseComponentProps,
@@ -20,6 +19,7 @@ import type {
   ExtensionComponentProps,
   PiletsBag,
   PiralPageMeta,
+  PiletEntry,
 } from './api';
 import type {
   ComponentConverters,
@@ -28,24 +28,22 @@ import type {
   RouterProps,
   LayoutProps,
   Errors,
+  RouteSwitchProps,
 } from './components';
 
 export interface StateDispatcher<TState> {
   (state: TState): Partial<TState>;
 }
 
-declare module './components' {
-  interface ComponentContext {
-    state: Atom<GlobalState>;
-  }
-}
-
-export type WrappedComponent<TProps> = ComponentType<Without<TProps, keyof BaseComponentProps>>;
+export type WrappedComponent<TProps> = ComponentType<PropsWithChildren<Without<TProps, keyof BaseComponentProps>>>;
 
 /**
  * The base type for pilet component registration in the global state context.
  */
 export interface BaseRegistration {
+  /**
+   * The pilet registering the component.
+   */
   pilet: string;
 }
 
@@ -53,7 +51,13 @@ export interface BaseRegistration {
  * The interface modeling the registration of a pilet page component.
  */
 export interface PageRegistration extends BaseRegistration {
+  /**
+   * The registered page component.
+   */
   component: WrappedComponent<PageComponentProps>;
+  /**
+   * The page's associated metadata.
+   */
   meta: PiralPageMeta;
 }
 
@@ -61,8 +65,17 @@ export interface PageRegistration extends BaseRegistration {
  * The interface modeling the registration of a pilet extension component.
  */
 export interface ExtensionRegistration extends BaseRegistration {
+  /**
+   * The wrapped registered extension component.
+   */
   component: WrappedComponent<ExtensionComponentProps<string>>;
+  /**
+   * The original extension component that has been registered.
+   */
   reference: any;
+  /**
+   * The default params (i.e., meta) of the extension.
+   */
   defaults: any;
 }
 
@@ -86,6 +99,10 @@ export interface ComponentsState extends PiralCustomComponentsState {
    * The layout used for pages.
    */
   Layout: ComponentType<LayoutProps>;
+  /**
+   * The route switch used for determining the route registration.
+   */
+  RouteSwitch: ComponentType<RouteSwitchProps>;
   /**
    * A component that can be used for debugging purposes.
    */
@@ -96,10 +113,6 @@ export interface ComponentsState extends PiralCustomComponentsState {
  * The Piral global app sub-state container for app information.
  */
 export interface AppState {
-  /**
-   * Information for the layout computation.
-   */
-  layout: LayoutType;
   /**
    * Gets if the application is currently performing a background loading
    * activity, e.g., for loading modules asynchronously or fetching
@@ -157,7 +170,7 @@ export interface GlobalState extends PiralCustomState {
   /**
    * Gets the loaded modules.
    */
-  modules: Array<PiletMetadata>;
+  modules: Array<Pilet>;
   /**
    * The foreign component portals to render.
    */
@@ -200,10 +213,22 @@ export interface PiralActions extends PiralCustomActions {
    */
   initialize(loading: boolean, error: Error | undefined, modules: Array<Pilet>): void;
   /**
-   * Injects a pilet at runtime - removes the pilet from registry first if available.
+   * Injects an evaluated pilet at runtime - removes the pilet from registry first if available.
    * @param pilet The pilet to be injected.
+   * @returns The injected pilet.
+   */
+  injectPilet(pilet: Pilet): Pilet;
+  /**
+   * Adds a pilet at runtime by loading it, evaluating it, and then injecting it.
+   * @param pilet The pilet to be added.
+   * @returns The promise indicating when the pilet was fully added.
    */
-  injectPilet(pilet: Pilet): void;
+  addPilet(pilet: PiletEntry): Promise<void>;
+  /**
+   * Removes a pilet by unloading it and deleting all component registrations.
+   * @param name The name of the pilet to remove.
+   */
+  removePilet(name: string): Promise<void>;
   /**
    * Defines a single action for Piral.
    * @param actionName The name of the action to define.
@@ -232,11 +257,6 @@ export interface PiralActions extends PiralCustomActions {
    * @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.
@@ -277,7 +297,10 @@ export interface PiralActions extends PiralCustomActions {
    * @param path The name of the component.
    * @param component The component to use for rendering.
    */
-  setRoute<T = {}>(path: string, component: ComponentType<RouteComponentProps<T>>): void;
+  setRoute<T extends { [K in keyof T]?: string } = {}>(
+    path: string,
+    component: ComponentType<RouteComponentProps<T>>,
+  ): void;
   /**
    * Includes a new provider as a sub-provider to the current provider.
    * @param provider The provider to include.
@@ -294,6 +317,19 @@ export interface PiralActions extends PiralCustomActions {
    * @param entry The child to render.
    */
   showPortal(id: string, entry: 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: 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: ReactPortal, next: ReactPortal): void;
   /**
    * Dispatches a state change.
    * @param update The update function creating a new state.
@@ -315,7 +351,7 @@ export interface GlobalStateContext extends PiralActions, EventEmitter {
    * The global state context atom.
    * Changes to the state should always be dispatched via the `dispatch` action.
    */
-  state: Atom<GlobalState>;
+  state: UseBoundStore<GlobalState>;
   /**
    * The API objects created for the loaded pilets.
    */
@@ -324,6 +360,10 @@ export interface GlobalStateContext extends PiralActions, EventEmitter {
    * The available component converters.
    */
   converters: ComponentConverters<any>;
+  /**
+   * The navigation manager for the whole instance.
+   */
+  navigation: NavigationApi;
   /**
    * The initial options.
    */

package/src/types/utils.ts

@@ -60,7 +60,7 @@ export interface PiralStoreDataEvent<TValue = any> {
   expires: number;
 }
 
-declare module 'piral-base/lib/types' {
+declare module 'piral-base/lib/types/api' {
   interface PiralEventMap extends PiralCustomEventMap {
     'store-data': PiralStoreDataEvent;
   }

package/src/utils/compare.test.ts

@@ -1,73 +1,73 @@
-import { compare } from './compare';
+import { isSame } from './compare';
 
 describe('Compare Module', () => {
   it('compare works with numbers that are not equal', () => {
-    const result = compare(5, 2);
+    const result = isSame(5, 2);
     expect(result).toEqual(false);
   });
 
   it('compare works with numbers that are equal', () => {
-    const result = compare(7, 7);
+    const result = isSame(7, 7);
     expect(result).toEqual(true);
   });
 
   it('compare works with booleans that are not equal', () => {
-    const result = compare(true, false);
+    const result = isSame(true, false);
     expect(result).toEqual(false);
   });
 
   it('compare works with booleans that are equal', () => {
-    const result = compare(false, false);
+    const result = isSame(false, false);
     expect(result).toEqual(true);
   });
 
   it('compare works with strings that are not equal', () => {
-    const result = compare('foo', 'bar');
+    const result = isSame('foo', 'bar');
     expect(result).toEqual(false);
   });
 
   it('compare works with strings that are equal', () => {
-    const result = compare('gtest', 'gtest');
+    const result = isSame('gtest', 'gtest');
     expect(result).toEqual(true);
   });
 
   it('compare works with types that are not equal', () => {
-    const result = compare('5', 5 as any);
+    const result = isSame('5', 5 as any);
     expect(result).toEqual(false);
   });
 
   it('compare works with arrays of simple types that are not equal', () => {
-    const result = compare([1, 2, 3], [1, 2, 4]);
+    const result = isSame([1, 2, 3], [1, 2, 4]);
     expect(result).toEqual(false);
   });
 
   it('compare works with arrays of simple types that have different lengths', () => {
-    const result = compare([1, 2, 3], [1, 2]);
+    const result = isSame([1, 2, 3], [1, 2]);
     expect(result).toEqual(false);
   });
 
   it('compare works with arrays of simple types that are equal', () => {
-    const result = compare([1, 2, 3], [1, 2, 3]);
+    const result = isSame([1, 2, 3], [1, 2, 3]);
     expect(result).toEqual(true);
   });
 
   it('compare works with objects of simple types that are not equal', () => {
-    const result = compare({ a: 2, b: true, c: 'hi' }, { a: 2, b: false, c: 'hi' });
+    const result = isSame({ a: 2, b: true, c: 'hi' }, { a: 2, b: false, c: 'hi' });
     expect(result).toEqual(false);
   });
 
   it('compare works with objects of simple types that have different keys', () => {
-    const result = compare({ a: 2, b: true, c: 'hi' }, { a: 2, b: true, d: 'hi' });
+    const result = isSame({ a: 2, b: true, c: 'hi' }, { a: 2, b: true, d: 'hi' });
     expect(result).toEqual(false);
   });
 
   it('compare works with objects of simple types that have less keys', () => {
-    const result = compare({ a: 2, b: true, c: 'hi' }, { a: 2, b: true });
+    const result = isSame({ a: 2, b: true, c: 'hi' }, { a: 2, b: true });
     expect(result).toEqual(false);
   });
 
   it('compare works with objects of simple types that are equal', () => {
-    const result = compare({ a: 2, b: true, c: 'hi' }, { a: 2, b: true, c: 'hi' });
+    const result = isSame({ a: 2, b: true, c: 'hi' }, { a: 2, b: true, c: 'hi' });
     expect(result).toEqual(true);
   });
 });

package/src/utils/compare.ts

@@ -6,7 +6,7 @@ function compareObjects(a: any, b: any) {
   }
 
   for (const i in b) {
-    if (!compare(a[i], b[i])) {
+    if (!isSame(a[i], b[i])) {
       return false;
     }
   }
@@ -14,13 +14,33 @@ function compareObjects(a: any, b: any) {
   return true;
 }
 
-export function compare<T>(a: T, b: T) {
+function compareArrays(a: Array<any>, b: Array<any>) {
+  const l = a.length;
+
+  if (l === b.length) {
+    for (let i = 0; i < l; i++) {
+      if (!isSame(a[i], b[i])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return false;
+}
+
+export function isSame<T>(a: T, b: T) {
   if (a !== b) {
     const ta = typeof a;
     const tb = typeof b;
 
     if (ta === tb && ta === 'object' && a && b) {
-      return compareObjects(a, b);
+      if (Array.isArray(a) && Array.isArray(b)) {
+        return compareArrays(a, b);
+      } else {
+        return compareObjects(a, b);
+      }
     }
 
     return false;

package/src/utils/extension.test.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { render } from '@testing-library/react';
+import { reactifyContent, toExtension } from './extension';
+
+describe('Util Extension.', () => {
+  it('Convert some component to an extension component.', () => {
+    const Component = ({ title }) => <b>{title}</b>;
+    const piral: any = {};
+    const Extension = toExtension(Component);
+    const node = render(<Extension piral={piral} params={{ title: 'Foo' }} />);
+    expect(node.container.querySelectorAll('b').length).toBe(1);
+  });
+
+  it('reactifyContent.', async () => {
+    const container = document.body.appendChild(document.createElement('div'));
+    container.innerHTML = `<div>FOO<</div>`;
+    const result = reactifyContent(container.childNodes) as React.ReactElement;
+    const node = render(result);
+    expect(node.container.querySelectorAll('piral-slot').length).toBe(1);
+  });
+});

package/src/utils/extension.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import type {} from 'piral-debug-utils';
+import type { ExtensionComponentProps, WrappedComponent } from '../types';
+
+function removeAll(nodes: Array<ChildNode>) {
+  nodes.forEach((node) => node.remove());
+}
+
+interface SlotCarrierProps {
+  nodes: Array<ChildNode>;
+}
+
+const SlotCarrier: React.FC<SlotCarrierProps> = ({ nodes }) => {
+  const host = React.useRef<HTMLSlotElement>();
+
+  React.useEffect(() => {
+    host.current?.append(...nodes);
+    return () => removeAll(nodes);
+  }, [nodes]);
+
+  if (nodes.length) {
+    return <piral-slot ref={host} />;
+  }
+
+  return null;
+};
+
+/**
+ * Transforms the given component to an extension component.
+ * @param Component The component to transform.
+ * @returns The extension component (receiving its props via params).
+ */
+export function toExtension<T>(Component: React.ComponentType<T>): WrappedComponent<ExtensionComponentProps<T>> {
+  return (props) => <Component {...props.params} />;
+}
+
+/**
+ * Reactifies the list of child nodes to a React Node by removing the
+ * nodes from the DOM and carrying it in a React Node, where it would be
+ * attached at a slot.
+ * @param childNodes The child nodes to reactify.
+ * @returns The React Node.
+ */
+export function reactifyContent(childNodes: NodeListOf<ChildNode>): React.ReactNode {
+  const nodes: Array<ChildNode> = Array.prototype.filter.call(childNodes, Boolean);
+  removeAll(nodes);
+  return <SlotCarrier nodes={nodes} />;
+}

package/src/utils/foreign.test.ts

@@ -1,12 +1,30 @@
-import { createElement, createRef } from 'react';
-import { convertComponent, renderInDom } from './foreign';
+import * as React from 'react';
+import { changeDomPortal, convertComponent, renderInDom } from './foreign';
+import { DefaultLoadingIndicator } from '../defaults/DefaultLoadingIndicator';
 import { ForeignComponent } from '../types';
-import { DefaultLoadingIndicator } from '../components/DefaultLoader';
+
+// const StubComponent: React.FC = (props) => <div />;
+// StubComponent.displayName = 'StubComponent';
 
 describe('Util Foreign.', () => {
+  it('changeDomPortal changes dom in portal', () => {
+    const children = React.createElement('div');
+    const current: React.ReactPortal = { key: 'current', children: { children }, type: 'div', props: null };
+
+    const context = {
+      updatePortal: jest.fn(),
+    } as any;
+    const portalId = 'pid';
+    const element = document.createElement('piral-portal') as HTMLElement;
+    element.setAttribute(portalId, '100');
+
+    const result = changeDomPortal(portalId, current, context, element, DefaultLoadingIndicator, {});
+    expect(result).not.toEqual({});
+  });
+
   it('Convert component function throws error due to missing converter function.', () => {
     const t = () => {
-      convertComponent(null, createElement('div'));
+      convertComponent(null, React.createElement('div'));
     };
     expect(t).toThrow('No converter for component of type "div" registered.');
   });
@@ -17,7 +35,7 @@ describe('Util Foreign.', () => {
     };
     const result = convertComponent(() => {
       return fComponent;
-    }, createElement('div'));
+    }, React.createElement('div'));
     expect(result).toEqual(fComponent);
   });
 
@@ -25,10 +43,10 @@ describe('Util Foreign.', () => {
     const context = {
       showPortal: jest.fn(),
     } as any;
-    const portalId = 'data-portal-id';
-    const element = document.createElement('div') as HTMLDivElement;
+    const portalId = 'pid';
+    const element = document.createElement('piral-portal') as HTMLElement;
     element.setAttribute(portalId, '100');
-    var result = renderInDom(context, element, DefaultLoadingIndicator, {});
+    var [result] = renderInDom(context, element, DefaultLoadingIndicator, {});
     expect(result).toBe('100');
   });
 
@@ -36,8 +54,8 @@ describe('Util Foreign.', () => {
     const context = {
       showPortal: jest.fn(),
     } as any;
-    const element = document.createElement('div') as HTMLDivElement;
-    var result = renderInDom(context, element, DefaultLoadingIndicator, {});
-    expect(result).toBeUndefined();
+    const element = document.createElement('piral-portal') as HTMLElement;
+    var [result] = renderInDom(context, element, DefaultLoadingIndicator, {});
+    expect(result).toBe('root');
   });
 });

package/src/utils/foreign.ts

@@ -1,7 +1,36 @@
-import { createElement, ComponentType } from 'react';
+import { createElement, ComponentType, ReactPortal } from 'react';
 import { createPortal } from 'react-dom';
 import { GlobalStateContext, ForeignComponent } from '../types';
 
+export const extensionName = 'piral-extension';
+export const portalName = 'piral-portal';
+export const slotName = 'piral-slot';
+
+export function attachDomPortal<TProps>(
+  id: string,
+  context: GlobalStateContext,
+  element: HTMLElement | ShadowRoot,
+  component: ComponentType<TProps>,
+  props: TProps,
+): [string, ReactPortal] {
+  const portal = createPortal(createElement(component, props), element as HTMLElement);
+  context.showPortal(id, portal);
+  return [id, portal];
+}
+
+export function changeDomPortal<TProps>(
+  id: string,
+  current: ReactPortal,
+  context: GlobalStateContext,
+  element: HTMLElement | ShadowRoot,
+  component: ComponentType<TProps>,
+  props: TProps,
+): [string, ReactPortal] {
+  const next = createPortal(createElement(component, props), element as HTMLElement);
+  context.updatePortal(id, current, next);
+  return [id, next];
+}
+
 export function convertComponent<T extends { type: string }, U>(
   converter: (component: T) => ForeignComponent<U>,
   component: T,
@@ -19,19 +48,17 @@ export function renderInDom<TProps>(
   component: ComponentType<TProps>,
   props: TProps,
 ) {
-  const portalId = 'data-portal-id';
+  const portalId = 'pid';
   let parent: Node = element;
 
   while (parent) {
-    if (parent instanceof Element && parent.hasAttribute(portalId)) {
-      const portal = createPortal(createElement(component, props), element as HTMLElement);
+    if (parent instanceof Element && parent.localName === portalName && parent.hasAttribute(portalId)) {
       const id = parent.getAttribute(portalId);
-      context.showPortal(id, portal);
-      return id;
+      return attachDomPortal(id, context, element, component, props);
     }
 
     parent = parent.parentNode || (parent as ShadowRoot).host;
   }
 
-  return undefined;
+  return attachDomPortal('root', context, element, component, props);
 }

package/src/utils/guid.test.ts

@@ -1,6 +1,11 @@
-import { generateId } from './guid';
+import { buildName, generateId } from './guid';
 
 describe('Guid Utility Module', () => {
+  it('buildName returns name with its prefix', () => {
+    const result = buildName('Ma', 'Majd');
+    expect(result).toEqual('Ma://Majd');
+  });
+
   it('Generates two consecutive different guids', () => {
     const guid1 = generateId();
     const guid2 = generateId();

package/src/utils/helpers.test.ts

@@ -8,9 +8,61 @@ import {
   prependItems,
   appendItems,
   updateKey,
+  replaceOrAddItem,
+  includeItem,
+  tryParseJson,
+  removeNested,
 } from './helpers';
 
 describe('Helpers Module', () => {
+  it('removeNested removes keys values', () => {
+    const obj = { d: 'test', z: ['test arr'] };
+    const result = removeNested(obj, () => true);
+    const expectedResult = { d: {}, z: {} };
+    expect(result).toEqual(expectedResult);
+  });
+
+  it('removeNested removes keys values with nested arrays', () => {
+    const obj = { z: [['test arr'], ['test arr2']] };
+    const result = removeNested(obj, () => true);
+    const expectedResult = { z: { '0': [], '1': [] } };
+    expect(result).toEqual(expectedResult);
+  });
+
+  it('removeNested splits keys values', () => {
+    const obj = { d: 'test', z: ['test arr'] };
+    const result = removeNested(obj, () => false);
+    const expectedResult = { d: { '0': 't', '1': 'e', '2': 's', '3': 't' }, z: { '0': 'test arr' } };
+    expect(result).toEqual(expectedResult);
+  });
+
+  it('tryParseJson parses a JSON string', () => {
+    const content = '{"result":true, "count":42}';
+    const result = tryParseJson(content);
+    expect(result).toEqual({ result: true, count: 42 });
+  });
+
+  it('tryParseJson return empty object if the content is not valid', () => {
+    const content = '"result":true, "count":42';
+    const result = tryParseJson(content);
+    expect(result).toEqual({});
+  });
+
+  it('includeItem adds an item to array', () => {
+    const result = includeItem([1, 2, 3], 4);
+    expect(result).toEqual([1, 2, 3, 4]);
+  });
+
+  it('replaceOrAddItem replaces the first item', () => {
+    const result = replaceOrAddItem([1, 2, 3], 4, () => true);
+    expect(result).toEqual([4, 2, 3]);
+  });
+
+  it('replaceOrAddItem adds the item the end', () => {
+    const result = replaceOrAddItem([1, 2, 3], 4, () => false);
+    expect(result).toEqual([1, 2, 3, 4]);
+  });
+
   it('prependItem works with an existing array', () => {
     const result = prependItem([1, 2, 3], 4);
     expect(result).toEqual([4, 1, 2, 3]);