swissgeol UI Core

This is the swissgeol UI Core Library. It implements components and behavior shared between web-based swissgeol applications. This library mainly provides Web Components built on Stencil, but also generates wrappers for Angular and React.

Getting Started

Select the guide that reflects your application's setup:

• Getting Started: Web Components if you want to use plain web components.
• Getting Started: Angular if you want to use the Angular wrappers.
• Getting Started: React if you want to use the React wrappers.

Afterward, make sure to have a look at Styling and Internationalization.

Getting Started: Web Components

To use swissgeol UI Core with plain web components, simply install the core library:

npm install @swissgeol/ui-core

Then, make sure to include the CSS at @swissgeol/ui-core/styles.css into your build process.

Also, the library expects the Inter font to be served at /assets/fonts/. You can find all required font files at @swissgeol/ui-core/dist/swissgeol-ui-core/assets/fonts/. You can simply copy these assets into your build folder, for example with Vite:

viteStaticCopy({
  targets: [
    {
      src: "node_modules/@swissgeol/ui-core/dist/swissgeol-ui-core/assets/*",
      dest: "assets",
    },
  ],
});

At startup, you will have to import the library:

import "@swissgeol/ui-core/import";

You can now use the web components in HTML.

Getting Started: Angular

To use swissgeol UI Core with Angular, install the core library and Angular extension:

npm install @swissgeol/ui-core
npm install @swissgeol/ui-core-angular

First, add the library's CSS and fonts to your build:

{
  "targets": {
    "build": {
      "options": {
        "assets": [
          {
            "glob": "**/*",
            "input": "node_modules/@swissgeol/ui-core/dist/swissgeol-ui-core/assets/fonts",
            "output": "/assets/fonts"
          }
        ],
        "styles": [
          "node_modules/@swissgeol/ui-core/dist/swissgeol-ui-core/swissgeol-ui-core.css"
        ]
      }
    }
  }
}

Then import the SwissgeolCoreModule whenever you want to use a wrapper component:

@NgModule({
  imports: [
    SwissgeolCoreModule,
    // ...
  ],
  // ...
})
export class AppModule {}

Note that as of now, we do not support standalone components / non-module-based applications due to issues with compiling Stencil to the Angular component target.

Also, the type checking for the wrapper components is as-of-yet very rudimentary, so you have to manually ensure that you conform to the library's interface.

Getting Started: React

To use swissgeol UI Core with React, install the core library and React extension:

npm install @swissgeol/ui-core
npm install @swissgeol/ui-core-react

Then, make sure to include the CSS at @swissgeol/ui-core/styles.css into your build process. You may simply import them in your code if your bundlers supports that:

import "@swissgeol/ui-core/styles.css";

Also, the library expects the Inter font to be served at /assets/fonts/. You can find all required font files at @swissgeol/ui-core/dist/swissgeol-ui-core/assets/fonts/. You can simply copy these assets into your build folder, for example with Vite:

viteStaticCopy({
  targets: [
    {
      src: "node_modules/@swissgeol/ui-core/dist/swissgeol-ui-core/assets/*",
      dest: "assets",
    },
  ],
});

You can now use the JSX components by importing from @swissgeol/ui-core-react.

The type checking for the wrapper components is as-of-yet very rudimentary, so you have to manually ensure that you conform to the library's interface.

Styling

All colors and font stlyes used within the library are fully backed by CSS variables. You can find them at src/theme/index.css

Most of the variables should be the same across all swissgeol applications. However, some colors, such as the branding, may differ between projects. To configure them simply add a :root block to your CSS:

/* Assets */
:root {
  --sgc-color-brand: #2e859d;
  --sgc-color-primary--active: #2e859d;
  --sgc-color-secondary--active: #bed7df;
}

/* Boreholes */
:root {
  --sgc-color-brand: #a65462;
  --sgc-color-primary--active: #a65462;
  --sgc-color-secondary--active: #ffd6dc;
}

/* Viewer (default) */
:root {
  --sgc-color-brand: #607d52;
  --sgc-color-primary--active: #607d52;
  --sgc-color-secondary--active: #b2d2a2;
}

Internationalization (i18n)

To enable the implementation of locale-dependent features, the swissgeol UI Core library internally uses a simple i18n service which handles translations. This service is mostly standalone and doesn't need any further configuration.

However, you will probably want to synchronize the library's translation language with your application. To do so, you can use the SwissgeolCoreI18n object:

import { SwissgeolCoreI18n, Language } from "@swissgeol/ui-core";

SwissgeolCoreI18n.setLanguage(Language.German);

The library's locale is as-of-yet never changed from within the library itself. This means that you are simply responsible for configuring the correct locale, but do not need to react to it being changed by anything else.

You can find the library's translations in the subfolders of src/locales/.

Development

In local development, a simple server is available:

npm run start

This will expose all HTML files in src/. This way, we are able to develop and test our components directly inside the library itself.

To build the library, run:

npm run build

This will compile all available output targets, including the Angular und React wrapper libraries.

Angular & React

To test the compiled wrapper components, there are two simple client projects at packages/angular-client and packages/react-client. These two libraries automatically integrate with the latest output of npm run build.