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.

Element	Description	Docs & Examples	State
eox-chart	Dynamic chart with built-in data fetching	Docs & Examples	⭕️
eox-drawtools	Draw and manage features on a map	Docs & Examples	🟡
eox-geosearch	An autocompleted search input for geographic locations	Docs & Examples	🟡
eox-itemfilter	Filter/search large sets of items client-side or server-side	Docs & Examples	✅
eox-jsonform	Render a form from a JSON schema	Docs & Examples	🟡
eox-layercontrol	Manage and modify map layers	Docs & Examples	🟡
eox-layout	Easily create a UI layout	Docs & Examples	🟡
eox-map	Map with powerful tools & helpers	Docs & Examples	✅
eox-stacinfo	Display properties of STAC files	Docs & Examples	🟡
eox-storytelling	StoryTelling tools based on markdown	Docs & Examples	✅
eox-timecontrol	Time control and playback for map layers	Docs & Examples	⭕️

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.

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 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.

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

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.

EOX-A / EOxElements

readme