Eoxelements

🚀 EOxElements

A collection of Web Components for geospatial UI elements, developed by EOX. These components offer a range of features to enhance geospatial web applications, providing dynamic charts, map drawing tools, feedback widgets, and more.

📚 Documentation, Examples

You can find descriptions, API documentation, and interactive examples here.

✨ Elements

• ⭕️ Alpha elements are currently in development and may undergo frequent and significant breaking changes.
• 🟡 Beta elements are mostly refined and ready for use, but there is still a possibility of breaking changes.
• ✅ Stable elements have been reviewed, documented, and have a complete API.

💻 Usage

For detailed descriptions and documentation of individual elements, please refer to the READMEs in the element subfolders.

📦 Bundlers (Vite, Webpack, etc.)

npm install @eox/<element>

import "@eox/<element>"
<eox-element></eox-element>

📜 Script tag

<eox-element></eox-element>

<script type="module">
import "@eox/<element>" from "https://cdn.skypack.dev/@eox/<element>"
</script>

🔧 Development

🌿 Branch naming convention

Inspired by this article.

Please name your branches in the format <element>/<changetype>/<name>:

main
map/feature/new-feature
map/fix/some-fix
chart/feature/new-feature
chart/fix/some-fix
[...]

⚙️ Initial Setup

To use npm workspaces and all elements correctly, please use Node.js >= 20.9.0 LTS.

Install all root and element dependencies:

npm install

In general, it is recommended to perform all actions from the root level, not from individual element folders. For example, if you want to build an element, use:

npm run build -w @eox/<element-name>

For more information, please refer to the npm workspace docs.

🚀 Dev server

To start the storybook dev server, use:

npm start

This will open the storybook server on localhost (port 6006), where you can use multiple element states for development. Edit the corresponding element *.stories.js files to create and work on multiple states of an element.

📝 Types

To generate all type outputs, use:

npm run types:generate:all

🧪 Test server

You can run individual tests using the Cypress testing GUI. It provides access to a suite of configurations for each element via component tests and E2E tests that combine multiple elements.

Component Tests

npm run cypress
--> select Component Testing
--> select a browser
--> select a spec

E2E Tests

End - to - end (E2E) tests use the bundled versions of the elements. To run E2E tests for a specific element, you first need to build that element using the build or watch (re - building on every change) command:

npm run watch -w <element>

To build/watch all elements, you can use:

npm run watch:all

Once the selected element(s) are built, you can run the corresponding tests in the Cypress GUI:

npm run cypress
--> select E2E Testing
--> select a browser
--> select a spec

🔄 Run automated tests

Automated tests (component & E2E tests) are performed by the GitHub action triggered on each PR to the main branch. You can trigger them locally by running:

npm run test:all // component & E2E
npm run test:component // only component tests
npm run test:e2e // only E2E test

Remember to build/watch all components before running E2E tests as described above.

🛠️ Useful commands

Format all elements:

npm run format:all

Lint/fix all elements:

npm run lint:all
npm run lint:fix:all

Type checking:

npm run types:generate:all
npm run typecheck

If you are using VS Code and the intellisense feature shows different errors than the CLI typecheck, you can set the following settings:

{
    "typescript.tsdk": "./node_modules/typescript/lib",
    "typescript.enablePromptUseWorkspaceTsdk": true
}

If something doesn't work properly, sometimes it helps to clean the entire setup and delete all node modules to start fresh:

npm run clean
--> deletes all node_module folders
npm install

🆕 Bootstrapping a new element

In essence, all you need is a new subfolder in the . Additionally, it is recommended to add the corresponding entries in preview.js (to have a centralized place for all element imports into storybook) and release-please-config.json (for release automation). Some more recommendations include:

• The preferred language for new elements is JS + JSDoc (for type checking with TypeScript).
• The preferred bundler is Vite.
• Component tests (done via Cypress) should only test the specific element, and everything else should be ideally mocked.
• If needed, web - component - creating frameworks such as lit are useful.

Some things are handled by the root "system":

• Testing (centralized Cypress setup, automatically looking for *.cy.js files inside the elements subfolder).
• Linting & formatting (scripts in the root package.json - see the section above).
• Storybook (centralized Storybook setup, automatically looking for *.stories.js files inside the elements subfolder).

📜 Previous versions

The main branch of this project contains the v2 version of EOxElements. For the (legacy) v1 EOxElements, please see the v1 branch.