EOxElements

A Web Component collection of geospatial UI elements, crafted by EOX.

# Documentation, Examples

Please find descriptions, API docs and interactive examples here.

# Elements

• ⭕️ Alpha elements are in-development and may have many frequent breaking
  changes.
• 🟡 Beta elements are mostly polished and ready for use, but may still have
  breaking changes.
• ✅ Stable elements are reviewed, documented, and API complete.

# Usage

For detailed descriptions and documentation on the individual elements, please check out 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](https://betterprogramming.pub/enabling-monorepo-with-a-simple-single-github-repository-39bc6347abba# 391d).

Please name your branches <element>/<changetype>/<name>:

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

# # Initial Setup

In order to use npm workspaces and all the elements properly, please use Node.js >= 20.9.0 LTS.

Install all root and all element dependencies:

npm install

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

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

Please refer to [the npm workspace docs](https://docs.npmjs.com/cli/v7/using-npm/workspaces# running-commands-in-the-context-of-workspaces) for more information.

# # Dev server

To start the storybook dev server, use:

npm start

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

# # Types

In order to generate all types output, use:

npm run types:generate:all

# # Test server

You can run individual tests by using the Cypress testing GUI. It offers access to a suite of configurations for each element via component tests, and E2E tests combining 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 bundleded versions of the elements. In order to be able to run E2E tests for a specific element you need to build that element first, using the build or the 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 main. 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

Temember to build/watch all components before running E2E tests as specified 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 does not 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 what is needed is a new subfolder in the /elements directory. Additionally, it is recommended to also add the corresponding entries in preview.js (to have a centralized place for all the 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, everything else is ideally mocked
• if needed, webcomponent-creating frameworks such as lit are handy

Some things are handled by the root "system":

• testing (centralized Cypress setup, automatically looking for *.cy.js files inside elements subfolder)
• linting & formatting (scripts in root package.json - see section above)
• storybook (centralized Storybook setup, automatically looking for *.stories.js files inside 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.