Dashboard: microapp v2

[koonpeng]

These are changes to the "microapp" architecture to make it more modular. The goal is to eventually combine react-components and the current dashboard and make it into a framework from which new dashboards can be easily created.

Configurable Microapps

Previously microapp is a "one and done" thing where there is no way to customize them. Now microapps can have customization options via a factory method.

foo.tsx

export interface FooProps {
  greeting: string
}

export default function Foo({ greeting }: FooProps) {
  return <div>{greeting}</div>
}

foo-app.ts

export default function createFooApp(config: FooProps) {
  return createMicroApp('foo', 'Foo', () => import('./foo'), (settings) => config);
}

The fourth argument to createMicroApp is a callback that returns the props that will be passed to the component when rendering. The map app is one example where the pattern is used.

MicroApp with Settings

On top of configurable micro apps, they can now also store runtime settings, in the props callback in createMicroApp, it receives a settings object, which has a microAppSettings: { [k: string]: unknown } field. Micro apps can store their settings there under their appId.

Lazy loaded Microapps

All microapps are now lazy loaded, notice above that when creating the foo app, the Foo component is loaded via a dynamic import. This allows vite to code split the micro apps and load only the microapps that are currently being used in a workspace.

Currently this results in reduction of the largest bundle from ~3mb to ~1.5mb.

Deferred Contexts

Normally contexts must always have a default value, in some cases, we may have a context that must always be available but it is not possible to set a default value. Previously the solution is to use null as the default value but through the blessing and curse of typescript, it means that we must have a non null assertion everywhere we use it. RmfIngress is one such example where it creates a lot of boilerplate.

Deferred contexts is a convenient wrapper that does the assertions. It will throw an error if no value is provided to the context yet.

export const [useFoo, FooProvider] = createDeferredContext<Foo>();

function MyComponent() {
  const foo = useFoo();
  foo.doStuff(); // no need for null assertion
  ...
}

function App() {
  const foo = new Foo();
  return <FooProvider value={foo}><MyComponent /></FooProvider>;
}

Easy dashboard customization

With the new microapps architecture, a new dashboard can be easily created with minimal code. Below is an example to create a minimal dashboard with a map, doors, lifts, robots and mutex groups app.

const mapApp = createMapApp({
  attributionPrefix: 'Open-RMF',
  defaultMapLevel: 'L1',
  defaultRobotZoom: 20,
  defaultZoom: 6,
});

const homeWorkspace: InitialWindow[] = [
  {
    layout: { x: 0, y: 0, w: 7, h: 4 },
    microApp: robotsApp,
  },
  { layout: { x: 8, y: 0, w: 5, h: 8 }, microApp: mapApp },
  { layout: { x: 0, y: 0, w: 7, h: 4 }, microApp: doorsApp },
  { layout: { x: 0, y: 0, w: 7, h: 4 }, microApp: liftsApp },
  { layout: { x: 8, y: 0, w: 5, h: 4 }, microApp: robotMutexGroupsApp },
];

export default function App() {
  return (
    <RmfDashboard
      apiServerUrl="http://localhost:8000"
      trajectoryServerUrl="http://localhost:8006"
      authenticator={new StubAuthenticator()}
      helpLink="https://osrf.github.io/ros2multirobotbook/rmf-core.html"
      reportIssueLink="https://github.com/open-rmf/rmf-web/issues"
      resources={{ fleets: {}, logos: { header: '/resources/defaultLogo.png' }}}
      tasks={{
        allowedTasks: [],
        pickupZones: [],
        cartIds: [],
      }}
      tabs={[
        {
          name: 'Home',
          route: '',
          element: <Workspace initialWindows={homeWorkspace} />,
        },
      ]}
    />
  );
}

Theming

Previously, themes are fixed, the only way to change the theme is to change the dashboard itself. With the move to a dashboard framework architecture, it is now possible to create dashboards with different themes. The examples/custom-theme shows an example of a dashboard with custom theme.

[aaronchongth]

Thanks for the herculean effort! I've not looked at the code in detail yet, but started running some of my usual tests of the dashboard, and wanted to highlight some issues and questions first,

• dashboard crashes when a task is completed (more specifically an alert is supposed to pop up)
  

[aaronchongth]

Thanks for adding this in, should we add some comments about this patch as well?

I'm not very familiar with patches in this manner, the .patch file was written by you manually, is that right? Or was it recommended somewhere?

[koonpeng]

It was a known problem with mui and three-fiber, the only solution I found is to do a hacky patch.

[aaronchongth]

To addon, I've found that pages (tabs) are no longer contained in the viewport, and users are required to scroll, to view the lift table under System Overview as well

[koonpeng]

To addon, I've found that pages (tabs) are no longer contained in the viewport, and users are required to scroll, to view the lift table under System Overview as well

Yeah, we no longer force the height of the workspace. But it is still possible to put all the micro apps without scrolling if you change the layout.

[koonpeng]

Thanks for the herculean effort! I've not looked at the code in detail yet, but started running some of my usual tests of the dashboard, and wanted to highlight some issues and questions first,

• dashboard crashes when a task is completed (more specifically an alert is supposed to pop up)
  

Thanks for helping to test, should be fixed now

[aaronchongth]

Just these 2 questions/comments, but otherwise LGTM

[aaronchongth]

Was the admin actions menu item left out for a reason?

[koonpeng]

It's just testing left overs, uncommented it now.

[aaronchongth]

I think we'll need to find a way to toggle the custom tab based on APP_CONFIG_ENABLE_CUSTOM_TABS, as well as the admin tab with APP_CONFIG_ENABLE_ADMIN_TAB

Or was the whole idea to remove the config variables, and let users set up the dashboard however they want with this new way? If so, then the admin tab should also be added in

or is the admin tab left out because we haven't worked out authz and actions mapping properly?

[koonpeng]

Yeah the plan is to have no build time config variables, after this transitions to a framework library, we can't have build time variables unless we integrate the build system into the framework as well.

Whether to have custom tabs can be easily configured by downstream with allowDesignMode, they can also configure the number of custom tabs and if "builtin" tabs can be customized.

The admin tab is more tricky, until the backend supports proper authz, we should never show the admin tab. But when it does support authz, we should always show the admin tab if the user is an admin. The problem is that in terms of DX, it may be disruptive to force include a tab that the user did not configure. Most likely it will not be a "tab" and instead be accessed from the user icon similar to the admin panel.

[aaronchongth]

LGTM so far! With these changes I think we'll need to start documenting how the dashboard app can be configured overall, could you also help add that in?

[koonpeng]

There are some docs added in #1007. https://github.com/open-rmf/rmf-web/tree/koonpeng/merge-react-components/packages/rmf-dashboard-framework/docs, haven't really fully tested them in practice, would appreciate if you can help beta test it!

[aaronchongth]

Thanks for pointing to the WIP docs, I've done a first pass on it so far and it looks good. We'll defer the update of documentation to #1007 then.

LGTM! Thanks!