Apex Toolbar

Overview

This monorepo implements a web component version of the Apex toolbar via StencilJS, provides the wrappers needed to natively integrate with React, Angular, vanilla JS, and Vue, and includes example apps that consume each of the wrappers for demo purposes.

pnpm is used to manage this monorepo workspace. To install all dependencies for all sub-projects at once, see the scripts section below.

Requirements

• Nodejs ^22.0.0
• pnpm 9.15.0

Install

The first time that you start up the project, you'll need to ensure the apps are pnpm install'd after the packages have run pnpm install and pnpm build. Here's the order of operations to run from apex-toolbar:

pnpm install:core
pnpm build:core

pnpm install:frameworks
pnpm build:frameworks

pnpm install:apps
pnpm build:apps

Structure

This project has two main areas: packages/ and apps/.

packages/

Framework wrappers that bundle the core Stencil web component into each supported framework.

• packages/core: Stencil project that contains the raw Stencil web components. Not published.
• packages/react-toolbar: Stencil wrapper for React based projects, e.g. Next.js or React. Published as @apex/react-toolbar
• packages/angular-workspace/projects/angular: Stencil wrapper for Angular components. Published as @apex/angular-toolbar
• packages/js-toolbar: Stencil wrapper for vanilla JS component. Published as @apex/js-toolbar
• packages/vue-toolbar: Stencil wrapper for Vue based projects. Published as @apex/vue-toolbar

apps/

Demo apps

• apps/react: basic React + Vite application
• apps/angular: Angular application
• apps/js: Vanilla JS implementation
• apps/vue: basic Vue + Vite application

Scripts

The following scripts are configured for you to operate this codebase:

Build all packages

pnpm run build

Run demo app

This project contains example apps to test the integration of the Apex toolbar web component. Run these commands to view the toolbar in different UI flavors:

pnpm start:react
pnpm start:angular
pnpm start:js
pnpm start:vue

Local development

Develop using the Stencil dev server

Has hot module reloading.

pnpm dev

Develop using a demo app

You can choose to start up the dev server for a demo app if you want to see your changes in the context of a consuming application. You'll need to manually run pnpm build after each change to a Stencil package. For example:

In one terminal:

pnpm start:react

Make some changes to the toolbar and save.

In another terminal:

pnpm build

Publishing

TODO: Set up .gitlab-ci.yml

Nuances/Gotchas/Intrinsic Knowledge

Monolithic Component

The toolbar file is large. We had initially broken this out into multiple components to make it easier to read and maintain. However, this introduced a number of problems from styling issues all the way to packaging issues, so we decided to leave it as one component.

For ease of navigation within the large component template, we left comments above what each section is:

1. NAVIGATION MENU - if provided with a navigation callback, this will display the cog icon. clients are responsible for bringing their own navigation UI
2. APPLICATION AREA - this is the area where the app icon and name are placed
3. WIDGET AREA - this is where developers can place widgets
4. SETTINGS MENU - if provided with a settings callback, this will display the cog icon. clients are responsible for bringing their own settings UI
5. APPLICATION MENU - the user's application list flyout
6. PROFILE MENU - the user's profile/logout flyout
7. MOBILE TOOLBAR - this is the mobile layout

If you attempt to break it out into multiple, easier to work with components, you need to:

1. create a css file for every component and import it -- styles will not work without this
2. each component needs shadow set to true to reset the css styles, otherwise you will run into some funky edge cases
3. drill props like theme all the way down since css resets
4. this means that you will also need to add the class dark at the root of each broken-out component based on a theme prop
5. find a way to not include the broken out components into the build, thus exposing them to clients