Cal-Adapt Svelte Components

This repository is for developing new UI Components for Cal-Adapt.org. These components use the Svelte JavaScript framework and IBM Carbon Design system.

The rationale for this component repository is:

1. To reduce the time for developing and iterating on UI components for Cal-Adapt.

2. Develop components in isolation so that they may be compatible in other Cal-Adapt related projects.

Changelog

View Change Log

The Components

Search with auto-suggest

A search box component with auto-suggest. Similar to the CDS ComboBox but with some corrections to aria and role attributes for improved accessibility.

• Component code
• Demo

Behavior Notes

Note that the Search component will not filter list items on its own, it's up to you to implement filtering. One way to do this is by using an on:input binding and filtering the suggestions prop based on what the user types. For suggestions that are retrieved asyncronously, e.g. from a RESTful API, it is recommended to debounce the input event handler.

Props

Events

Dispatched Events

• change: dispatched when a list item from the Search component's suggestions list is selected a change custom event is dispatched with the selectedItem.

• clear: dispatched when the clear search input button is clicked.

Forwarded Events

Additionally, the following native events may be listened for on the Search component's input element:

• input
• focus
• blur
• keydown
• keyup

Static Map

The Static Map is intended to be used within a tool's settings panel as a locator map that displays the geographic boundary selected by the user. In most tools, it is wrapped in an HTML <button> element that when clicked on displays a modal which allows the user to change the selected location. The Static Map is not responsible for changing the location, only for handling a click event that may be used to trigger opening a modal.

• Component code
• Demo

Props

Events

Forwarded Events

• click

Note: The click event handler is only exposed when useButton is set to true.

Developing

Once you've installed dependencies with npm install, start a development server:

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Building

To create a production version of your app:

npm run build

You can preview the production build with npm run preview.

Note: To deploy your app, you may need to install an adapter for your target environment.

Packaging

To compile the components from the src/lib component directory so that they may be used as a dependency within another project do:

npm run package

This will create a local package/ directory with the compiled Svelte components, meaning all TypeScript will be converted to normal JavaScript and all Sass will be converted to normal CSS.

Publishing to NPM and Github

The components in this repository are made publicly available on NPM and Github. The steps for publishing them are as follows:

npm version patch # updates the package version (including in git)
npm run package
npm publish --access public
git push origin --tags

Then create a release on Github with the package code by doing:

cd ./package
npm run pack

This will create a berkeley-gif-cal-adapt-svelte-components-<x.x.x>.tzg file in the package/ directory which may be included with the Github release.

Linking

The package directory of this repo may be npm link'd to another project for local development.

First, from the ./package directory of this repository (assuming you have already done npm run package):

npm link

Then from the project directory that uses this component library:

npm link cal-adapt-svelte-components

Now when the package directory is updated the project using it will reflect those updates. This means whenever components are updated in src/lib the script npm run package will need to be run in order to reflect updates.

Note that if you have multiple versions of NodeJS installed that you need to make sure you're using npm link with the same NodeJS and NPM version.

Note that the caladapt-website-2021 project uses Sapper (the predecessor to SvelteKit) and in order to import components from this repo you must use the component's full path.

For example:

import SomeComponent from "cal-adapt-svelte-components/SomeComponent/SomeComponent.svelte";

Sapper / Webpack will not be able to resolve the bare module import and thus the following will fail:

import { SomeComponent } from "cal-adapt-svelte-components";

Tests

Component unit tests are written in TypeScript and run via Vitest, @testing-library/svelte and @testing-library/jest-dom.

To run component unit tests do

npm run test

To have tests run in watch mode do:

npm run test:watch

Check Sass Build

The rebuild times for the project's global Sass is a little slow with Vite. To verify that the project's global Sass compiles successfully you may do:

npm run sass:check

If all goes well no output will be shown. Any errors will be printed to the console.

Code Credits

create-svelte

This project was bootstrapped using SvelteKit's create-svelte project generator:

npm create svelte@latest cal-adapt-svelte-components