react-hooks

react-hooks

A Pandino library providing handy tools for React-based applications.

Context

This package is part of the pandino-root monorepo. For detailed information about what is Pandino / how this package fits into the ecosystem, please consult with the related documentation(s).

Usage

PandinoProvider

In order for hooks provided by this library to work, as a first step we must initialize the PandinoProvider:

import { createRoot } from 'react-dom/client';
import Pandino from '@pandino/pandino';
import loaderConfiguration from '@pandino/loader-configuration-dom';
import { PandinoProvider } from '@pandino/react-hooks';

const root = createRoot(document.querySelector('#root')!);

const pandino = new Pandino({
  ...loaderConfiguration,
});

await pandino.init();
await pandino.start();

// FYI: PandinoProvider's `ctx` prop expects any BundleContext instance, it doesn't need to be the system bundle's context. 
root.render(
  <PandinoProvider ctx={pandino.getBundleContext()}>
    <YourAppHere />
  </PandinoProvider>,
);

useBundleContext

Use this hook to obtain the BundleContext reference registered with PandinoProvider

import type { FC } from 'react';
import { useBundleContext } from '@pandino/react-hooks';

export const MyComponent: FC = () => {
    const { bundleContext } = useBundleContext();
    
    console.log(bundleContext);
    
    // ...
};

useTrackService

This is a simple hook which expects a filter parameter and returns a Service or undefined.

When a service is removed from the system or if is not present to begin with, the hook will trigger the component and the returned value will be undefined.

Developers MUST handle the undefined scenarios explicitly.

import type { FC } from 'react';
import { OBJECTCLASS } from '@pandino/pandino-api';
import { useTrackService } from '@pandino/react-hooks';

export const MyComponent: FC = () => {
    const { service: serviceImpl } = useTrackService<ServiceInterface>(`(${OBJECTCLASS}=${SERVICE_INTERFACE_KEY})`);
    
    serviceImpl?.someMethod(); // Notice the usage of `?`
    
    // ...
};

useTrackComponent

This hook works similarly to useTrackService, the only difference is that it handles React components.

Component contract:

import type { FC } from 'react';
export const CUSTOM_COMPONENT_INTERFACE_KEY = '@some-scope/component-api/CustomComponent';

export interface CustomComponent extends FC<ComponentProps> {}

export interface ComponentProps {
  firstName: string;
  lastName?: string;
}

Component implementation:

import { useState } from 'react';
import type { CustomComponent } from '@some-scope/component-api';

export const ComponentOne: CustomComponent = (props) => {
    const [data, setData] = useState<{ firstName: string; lastName?: string }>({ ...props });

    return (
        <div className="component-one" style={{ border: '1px solid black', padding: '1rem' }}>
            <h3>Component One</h3>
            <p>FirstName: {data.firstName}</p>
            <p>LastName: {data.lastName}</p>
        </div>
    );
};

Component registration:

import type { BundleActivator, BundleContext, ServiceRegistration } from '@pandino/pandino-api';
import type { CustomComponent } from '@some-scope/component-api';
import { CUSTOM_COMPONENT_INTERFACE_KEY } from '@some-scope/component-api';
import { ComponentOne } from './ComponentOne';

export default class SomeActivator implements BundleActivator {
  private reg?: ServiceRegistration<CustomComponent>;

  async start(context: BundleContext) {
    this.reg = context.registerService<CustomComponent>(CUSTOM_COMPONENT_INTERFACE_KEY, ComponentOne);
  }

  async stop(context: BundleContext) {
    this.reg?.unregister();
  }
}

Consumer app:

import type { FC } from 'react';
import { OBJECTCLASS } from '@pandino/pandino-api';
import { useTrackComponent } from '@pandino/react-hooks';
import type { CustomComponent } from '@some-scope/component-api';
import { CUSTOM_COMPONENT_INTERFACE_KEY } from '@some-scope/component-api';

export const MyComponent: FC = () => {
    const ExternalComponent = useTrackComponent<CustomComponent>(`(${OBJECTCLASS}=${CUSTOM_COMPONENT_INTERFACE_KEY})`);

    if (ExternalComponent) {
        return <ExternalComponent {...someProps} />;
    }

    return <>fallback content</>;
};

ComponentProxy

The ComponentProxy component can be used as a wrapper which has a filter prop, and renders the corresponding component if found. Otherwise it renders it's children.

In essence it is a shorthand / syntax sugar for useTrackComponent

import type { FC } from 'react';
import { useState } from 'react';
import { OBJECTCLASS } from '@pandino/pandino-api';
import { ComponentProxy } from '@pandino/react-hooks';
import { CUSTOM_COMPONENT_INTERFACE_KEY } from '@some-scope/component-api';

export const App: FC = () => {
  const [firstName] = useState<string>('John');

  return (
    <ComponentProxy filter={`(${OBJECTCLASS}=${CUSTOM_COMPONENT_INTERFACE_KEY})`} firstName={firstName}>
      <div className={'fallback'}>fallback for: {firstName}</div>
    </ComponentProxy>
  );
};

All props are passed to the found component except filter.

Prop matching between desired component props and children are not ensured.

This component (currently) cannot validate props!

License

Eclipse Public License - v 2.0