Skip to content

Latest commit

 

History

History
261 lines (202 loc) · 9.54 KB

README.md

File metadata and controls

261 lines (202 loc) · 9.54 KB
Raw

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