piral-core 0.15.0-alpha.4041 → 0.15.0-alpha.4231

package/src/components/ExtensionSlot.test.tsx

@@ -49,6 +49,11 @@ const state = {
           component: StubComponent3,
         },
       ],
+      lol: [
+        {
+          component: StubComponent1,
+        },
+      ],
     },
   },
 };
@@ -118,7 +123,7 @@ describe('Extension Module', () => {
   it('overrides the empty renderer on not available extension', () => {
     const node = mount(<ExtensionSlot name="qxz" empty={() => <StubComponent1 key="empty" />} />);
     expect(node.find(StubComponent1).length).toBe(1);
-    expect(node.find(StubComponent1).length).toBe(1);
+    expect(node.find(StubComponent2).length).toBe(0);
   });
 
   it('overrides the empty renderer on an available extension', () => {
@@ -138,4 +143,30 @@ describe('Extension Module', () => {
     expect(node.find(StubComponent1).length).toBe(1);
     expect(node.find(StubComponent2).length).toBe(1);
   });
+
+  it('does not use the render function with empty when emptySkipsRender is set', () => {
+    const node = mount(
+      <ExtensionSlot
+        name="foo"
+        emptySkipsRender
+        empty={() => <StubComponent2 key="empty" />}
+        render={(nodes) => <StubComponent1 children={nodes} />}
+      />,
+    );
+    expect(node.find(StubComponent1).length).toBe(0);
+    expect(node.find(StubComponent2).length).toBe(1);
+  });
+
+  it('does use the render function without empty independent if emptySkipsRender is set', () => {
+    const node = mount(
+      <ExtensionSlot
+        name="lol"
+        emptySkipsRender
+        empty={() => <StubComponent2 key="empty" />}
+        render={(nodes) => <StubComponent1 children={nodes} />}
+      />,
+    );
+    expect(node.find(StubComponent1).length).toBe(2);
+    expect(node.find(StubComponent2).length).toBe(0);
+  });
 });

package/src/components/ExtensionSlot.tsx

@@ -20,33 +20,50 @@ const renderExtensions: [ExtensionRegistration] = [
     defaults: {},
     pilet: '',
     reference: {
-      displayName: 'RenderExtension',
+      displayName: 'AnyComponent',
     },
   },
 ];
 
+function defaultOrder(extensions: Array<ExtensionRegistration>) {
+  return extensions;
+}
+
 /**
  * The extension slot component to be used when the available
  * extensions of a given name should be rendered at a specific
  * location.
  */
 export function ExtensionSlot<T extends string>(props: ExtensionSlotProps<T>) {
-  const { name, render = defaultRender, empty, params, children } = props;
+  const {
+    name,
+    render = defaultRender,
+    empty,
+    params,
+    children,
+    emptySkipsRender = false,
+    order = defaultOrder,
+  } = props;
   const extensions = useGlobalState((s) => (name ? s.registry.extensions[name] || none : renderExtensions));
-  return render(
-    extensions.length === 0 && isfunc(empty)
-      ? [defaultRender(empty(), 'empty')]
-      : extensions.map(({ component: Component, reference, defaults = {} }, i) => (
-          <Component
-            key={`${reference?.displayName || '_'}${i}`}
-            children={children}
-            params={{
-              ...defaults,
-              ...(params || {}),
-            }}
-          />
-        )),
-  );
+  const isEmpty = extensions.length === 0 && isfunc(empty);
+  const content = isEmpty
+    ? [defaultRender(empty(), 'empty')]
+    : order(extensions).map(({ component: Component, reference, defaults = {} }, i) => (
+        <Component
+          key={`${reference?.displayName || '_'}${i}`}
+          children={children}
+          params={{
+            ...defaults,
+            ...params,
+          }}
+        />
+      ));
+
+  if (isEmpty && emptySkipsRender) {
+    return content[0];
+  }
+
+  return render(content);
 }
 
 ExtensionSlot.displayName = `ExtensionSlot`;

package/src/components/ForeignComponentContainer.test.tsx

@@ -1,13 +1,21 @@
 import * as React from 'react';
-import { render, unmountComponentAtNode } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
 import { ForeignComponentContainer } from './ForeignComponentContainer';
 
+async function render(element: any, container: Element) {
+  const root = createRoot(container);
+  root.render(element);
+  await act(() => Promise.resolve());
+  return root;
+}
+
 describe('ForeignComponentContainer component', () => {
-  it('mounts an HTML component', () => {
+  it('mounts an HTML component', async () => {
     const container = document.body.appendChild(document.createElement('div'));
     const mount = jest.fn();
     const component = { mount };
-    render(
+    await render(
       <ForeignComponentContainer $component={component} $context={undefined} $portalId="foo" innerProps={{}} />,
       container,
     );
@@ -15,28 +23,28 @@ describe('ForeignComponentContainer component', () => {
     container.remove();
   });
 
-  it('unmounts an HTML component', () => {
+  it('unmounts an HTML component', async () => {
     const container = document.body.appendChild(document.createElement('div'));
     const mount = jest.fn();
     const unmount = jest.fn();
     const component = { mount, unmount };
-    render(
+    const root = await render(
       <ForeignComponentContainer $component={component} $context={undefined} $portalId="foo" innerProps={{}} />,
       container,
     );
     expect(mount).toHaveBeenCalled();
     expect(unmount).not.toHaveBeenCalled();
-    unmountComponentAtNode(container);
+    root.unmount();
     expect(unmount).toHaveBeenCalled();
     container.remove();
   });
 
-  it('updates an HTML component', () => {
+  it('updates an HTML component', async () => {
     const container = document.body.appendChild(document.createElement('div'));
     const mount = jest.fn();
     const update = jest.fn();
     const component = { mount, update };
-    render(
+    const root = await render(
       <ForeignComponentContainer
         $component={component}
         $context={undefined}
@@ -47,20 +55,20 @@ describe('ForeignComponentContainer component', () => {
     );
     expect(mount).toHaveBeenCalled();
     expect(update).not.toHaveBeenCalled();
-    render(
+    root.render(
       <ForeignComponentContainer
         $component={component}
         $context={undefined}
         $portalId="foo"
         innerProps={{ a: 'foo' }}
       />,
-      container,
     );
+    await act(() => Promise.resolve());
     expect(update).toHaveBeenCalled();
     container.remove();
   });
 
-  it('forces re-rendering of an HTML component', () => {
+  it('forces re-rendering of an HTML component', async () => {
     const container = document.body.appendChild(document.createElement('div'));
     const componentDidMount = ForeignComponentContainer.prototype.componentDidMount;
     ForeignComponentContainer.prototype.componentDidMount = function () {
@@ -73,7 +81,7 @@ describe('ForeignComponentContainer component', () => {
     const update = jest.fn();
     const unmount = jest.fn();
     const component = { mount, update, unmount };
-    render(
+    const root = await render(
       <ForeignComponentContainer
         $component={component}
         $context={undefined}
@@ -85,27 +93,27 @@ describe('ForeignComponentContainer component', () => {
     expect(mount).toHaveBeenCalled();
     expect(unmount).not.toHaveBeenCalled();
     expect(update).not.toHaveBeenCalled();
-    render(
+    root.render(
       <ForeignComponentContainer
         $component={component}
         $context={undefined}
         $portalId="foo"
         innerProps={{ a: 'foo' }}
       />,
-      container,
     );
+    await act(() => Promise.resolve());
     expect(update).not.toHaveBeenCalled();
     expect(unmount).toHaveBeenCalled();
     container.remove();
   });
 
-  it('listens to render-html', () => {
+  it('listens to render-html', async () => {
     const container = document.body.appendChild(document.createElement('div'));
     const mount = jest.fn();
     const renderHtmlExtension = jest.fn();
     const component = { mount };
     const props = { piral: { renderHtmlExtension }, meta: {} };
-    render(
+    await render(
       <ForeignComponentContainer $component={component} $context={undefined} $portalId="foo" innerProps={props} />,
       container,
     );
@@ -113,6 +121,7 @@ describe('ForeignComponentContainer component', () => {
     const node = document.querySelector('[data-portal-id=foo]');
     expect(renderHtmlExtension).not.toHaveBeenCalled();
     node.dispatchEvent(new CustomEvent('render-html', { detail: {} }));
+    await act(() => Promise.resolve());
     expect(renderHtmlExtension).toHaveBeenCalled();
     container.remove();
   });

package/src/components/ForeignComponentContainer.tsx

@@ -1,7 +1,6 @@
 import * as React from 'react';
 import { isfunc } from 'piral-base';
-import { __RouterContext } from 'react-router';
-import { ForeignComponent, BaseComponentProps, ComponentContext } from '../types';
+import type { ForeignComponent, BaseComponentProps, ComponentContext } from '../types';
 
 interface ForeignComponentContainerProps<T> {
   $portalId: string;

package/src/components/PiralSuspense.tsx

@@ -2,7 +2,11 @@ import * as React from 'react';
 import { RegisteredErrorInfo, RegisteredLoadingIndicator } from './components';
 import { useGlobalState } from '../hooks';
 
-export const PiralSuspense: React.FC = ({ children }) => {
+export interface PiralSuspenseProps {
+  children?: React.ReactNode;
+}
+
+export const PiralSuspense: React.FC<PiralSuspenseProps> = ({ children }) => {
   const { error, loading } = useGlobalState((m) => m.app);
 
   return error ? (

package/src/components/PiralView-server.test.tsx

@@ -17,45 +17,45 @@ StubErrorInfo.displayName = 'StubErrorInfo';
 const StubLoader: React.FC = () => <div />;
 StubLoader.displayName = 'StubLoader';
 
-const StubRouter: React.FC = ({ children }) => <div>{children}</div>;
+const StubRouter: React.FC<React.PropsWithChildren<{}>> = ({ children }) => <div>{children}</div>;
 StubRouter.displayName = 'StubRouter';
 
-const StubLayout: React.FC = ({ children }) => <div>{children}</div>;
+const StubLayout: React.FC<React.PropsWithChildren<{}>> = ({ children }) => <div>{children}</div>;
 StubLayout.displayName = 'StubLayout';
 
 jest.mock('../hooks');
 jest.mock('./PiralRoutes');
 
 const state = {
-    app: {
-        error: undefined,
-        loading: true,
-    },
-    components: {
-        ErrorInfo: StubErrorInfo,
-        LoadingIndicator: StubLoader,
-        Router: StubRouter,
-        Layout: StubLayout,
-    },
-    registry: {
-        pages: {},
-        extensions: {},
-    },
-    portals: {},
-    routes: {},
-    provider: undefined,
+  app: {
+    error: undefined,
+    loading: true,
+  },
+  components: {
+    ErrorInfo: StubErrorInfo,
+    LoadingIndicator: StubLoader,
+    Router: StubRouter,
+    Layout: StubLayout,
+  },
+  registry: {
+    pages: {},
+    extensions: {},
+  },
+  portals: {},
+  routes: {},
+  provider: undefined,
 };
 
 (hooks as any).useGlobalState = (select: any) => select(state);
 
-(routes as any).PiralRoutes = ({ }) => <StubDashboard />;
+(routes as any).PiralRoutes = ({}) => <StubDashboard />;
 
 describe('Portal Module', () => {
-    it('In this test window should be undefined', () => {
-        state.app.loading = false;
-        state.app.error = undefined;
-        const node = render(<PiralView />);
-        expect(typeof window).toBe("undefined")
-        expect(node.length).toBe(1);
-    });
+  it('In this test window should be undefined', () => {
+    state.app.loading = false;
+    state.app.error = undefined;
+    const node = render(<PiralView children={undefined} />);
+    expect(typeof window).toBe('undefined');
+    expect(node.length).toBe(1);
+  });
 });

package/src/components/PiralView.tsx

@@ -17,6 +17,10 @@ export interface PiralViewProps {
    * The custom breakpoints for the different layout modi.
    */
   breakpoints?: LayoutBreakpoints;
+  /**
+   * The extra content.
+   */
+  children: React.ReactNode;
 }
 
 /**

package/src/components/ResponsiveLayout.tsx

@@ -11,7 +11,14 @@ export interface ResponsiveLayoutProps {
    * The individual breakpoints to be used for the different layouts.
    */
   breakpoints?: LayoutBreakpoints;
+  /**
+   * The actual layout component to render to transport.
+   */
   Layout: React.ComponentType<LayoutProps>;
+  /**
+   * The content to display.
+   */
+  children: React.ReactNode;
 }
 
 /**

package/src/components/wrapComponent.tsx

@@ -4,7 +4,7 @@ import { PortalRenderer } from './PortalRenderer';
 import { ForeignComponentContainer } from './ForeignComponentContainer';
 import { useGlobalStateContext } from '../hooks';
 import { convertComponent, none } from '../utils';
-import { AnyComponent, ComponentConverters, ForeignComponent, PiletApi, BaseComponentProps } from '../types';
+import type { AnyComponent, ComponentConverters, ForeignComponent, PiletApi, BaseComponentProps } from '../types';
 
 // this is an arbitrary start number to have 6 digits
 let portalIdBase = 123456;

package/src/defaults/DefaultRouter.tsx

@@ -1,8 +1,9 @@
 import * as React from 'react';
 import { BrowserRouter } from 'react-router-dom';
 import { useGlobalState } from '../hooks';
+import { RouterProps } from '../types';
 
-export const DefaultRouter: React.FC = ({ children }) => {
+export const DefaultRouter: React.FC<RouterProps> = ({ children }) => {
   const publicPath = useGlobalState((s) => s.app.publicPath);
   return <BrowserRouter basename={publicPath}>{children}</BrowserRouter>;
 };

package/src/hooks/setter.test.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { act } from 'react-dom/test-utils';
-import { render } from 'react-dom';
+import { createRoot } from 'react-dom/client';
 import { useSetter } from './setter';
 
 describe('UseSetter Hook Module', () => {
@@ -12,7 +12,8 @@ describe('UseSetter Hook Module', () => {
       return null;
     };
 
-    render(React.createElement(MyComponent), document.body.appendChild(document.createElement('div')));
+    const root = createRoot(document.body.appendChild(document.createElement('div')));
+    root.render(React.createElement(MyComponent));
     await act(() => Promise.resolve());
     expect(cb).toHaveBeenCalled();
   });

package/src/state/withApi.tsx

@@ -1,10 +1,9 @@
 import * as React from 'react';
-import { __RouterContext } from 'react-router';
 import { ErrorBoundary, wrapComponent } from '../components';
 import { defaultRender } from '../utils';
 import { AnyComponent, Errors, PiletApi, BaseComponentProps, GlobalStateContext } from '../types';
 
-const DefaultWrapper: React.FC = (props) => defaultRender(props.children);
+const DefaultWrapper: React.FC<React.PropsWithChildren<{}>> = (props) => defaultRender(props.children);
 
 function getWrapper(wrappers: Record<string, React.ComponentType<any>>, wrapperType: string) {
   const WrapAll = wrappers['*'];
@@ -26,7 +25,7 @@ function makeWrapper<TProps>(
   outerProps: any,
   wrapperType: string,
   errorType: keyof Errors,
-): React.FC<TProps> {
+): React.FC<React.PropsWithChildren<TProps>> {
   const OuterWrapper = context.readState((m) => getWrapper(m.registry.wrappers, wrapperType));
 
   return (props) => (

package/src/types/api.ts

@@ -1,4 +1,4 @@
-import type { ReactElement } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 import type { RouteComponentProps } from 'react-router';
 import type {
   PiletApi,
@@ -46,6 +46,10 @@ 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;
 }
 
 /**
@@ -70,6 +74,20 @@ export interface PageComponentProps<T = any, S = any> extends RouteBaseProps<T,
   meta: PiralPageMeta;
 }
 
+/**
+ * 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.
@@ -112,7 +130,7 @@ export interface PiletCoreApi {
    */
   registerExtension<TName>(
     name: TName extends string ? TName : string,
-    Component: AnyComponent<ExtensionComponentProps<TName>>,
+    Component: AnyExtensionComponent<TName>,
     defaults?: Partial<ExtensionParams<TName>>,
   ): RegistrationDisposer;
   /**
@@ -123,7 +141,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.

package/src/types/components.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react';
+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';
@@ -191,12 +191,21 @@ 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 props of the RouteSwitch component.

package/src/types/extension.ts

@@ -1,5 +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.
@@ -19,9 +20,27 @@ export interface BaseExtensionSlotProps<TName, TParams> {
    * for the specified extension.
    */
   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<ReactNode>): ReactElement<any, any> | null;
   /**

package/src/types/instance.ts

@@ -1,7 +1,8 @@
+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 { PiralConfiguration } from './config';
+import type { PiralConfiguration } from './config';
 
 /**
  * The props of the Piral context.
@@ -11,6 +12,7 @@ export interface PiralContextProps {
    * The specific Piral instance to be used.
    */
   instance?: PiralInstance;
+  children?: ReactNode;
 }
 
 /**

package/src/types/state.ts

@@ -1,4 +1,4 @@
-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';
@@ -41,12 +41,15 @@ declare module './components' {
   }
 }
 
-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;
 }
 
@@ -54,7 +57,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;
 }
 
@@ -62,8 +71,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;
 }