@spectrum-web-components/modal NPM

spectrum-web-components

Spectrum Web Components is a future-looking project to develop Adobe Spectrum design language based around web components, ES-Modules, and modern browser standards.

It will not support older browsers and will only target modern ever-green browsers that fully implement the Custom Elements V1 specification, e.g. Chrome, Firefox, Safari. Polyfills will be avoided as much as possible.

Requirements

NodeJS >= 12.18.3
Typescript
Browsers with Custom Elements V1 and Shadow DOM support, e.g. Chrome, Firefox, Safari, Edge (79+)
- Or appropriate polyfills in older browsers.

Getting Started

git clone https://github.com/adobe/spectrum-web-components.git
cd spectrum-web-components
yarn

The call to yarn will subsequently trigger scripting which will ensure that your local repo is adequately prepared to develop and run the packages in this library.

Typical development will involve running yarn storybook, yarn test, and yarn docs:start if you're making documentation changes.

Storybook

Testing & reviewing changes will typically involve running yarn storybook which will launch a browser window with the storybook pages. From there you can make changes in development and refresh the browser to pick them up.

You can run Storybook through the command:

yarn storybook

By default the resulting site will be available at http://localhost:8000, but the storybook command should launch a browser.

Documentation

The Spectrum Web Components documentation site is available via the following command:

yarn docs:start

By default the resulting site will be available at http://localhost:8080.

In the case that you'd like to serve and test a static build of the documentation from the root director of a server (localhost or otherwise), use:

yarn docs:build

Advanced development

There are several more commands that can be useful in specific scenarios:

yarn build:clear-cache to remove previously created artifacts of the tsc build process.
yarn spectrum-vars to ensure that theme files are up-to-date.
yarn process-icons to make sure that the most recent icons are included.
yarn process-spectrum to process the spectrum CSS style sources into the individual packages.
yarn build to make sure the most recent code base is represented in each package's lib folders. This happens automatically in the storybook command.

Linting

The project will be linted on a pre-commit hook, but you can also run the lint suite with yarn lint. It uses ESLint to lint the JS / TS files, and StyleLint to lint the CSS files.

Dependency Linting

There are downstream issues that can arise from multiple packages in this mono-repo using dependencies with mismatching version strings. This is particularly an issue for dependencies below 1.0.0 but can be exacerbated in that context and others by more strict settings that can be applied in various package managers. By default, Lerna will bump version numbers of internal dependencies when the various packages are published and the depended version is pointing to the latest release, which can help to mitigate this issue. This can be further mitigated by using ^0.0.0 structured dependency versions, the ^ allowing for the highest amount of upward flexibility in satisfying the dependency. When using these version strings, yarn lint: versions which ensure that all instances of those strings for the same dependency match across the repo.

Testing

Unit Tests

Unit tests are run with Web Test Runner in Playwright using the Chai, Mocha and Sinon helper libraries. These tests can be executed with:

yarn test

During development you may wish to use yarn test:watch to automatically build and re-run the test suites.

Screenshot Testing

Note: visual regression is done automatically on pull requests via CircleCI, so unless you're making larger changes it's okay to make use of that.

Visual regressions are tracked via screenshot testing powered by Puppeteer. There are two types of visual testing built into this library: those that should only be run in CircleCI to power the continuous integration workflow and those that can be run on your local machine. Due to the font metrics not being identical, it is difficult to rely on screenshot based testing across OSes, so if you'd like to leverage these tests to manage changes you are making, be sure to create a local baseline before you start to develop.

To create a baseline, and then later compare the current state of the repo to it, use the following commands:

yarn storybook:build # creates the test assets
yarn test:visual:baseline:local --color=light --scale=medium
# ...
yarn test:visual:local --color=light --scale=medium

These tests are run against the built Storybook artifacts, so be sure to run yarn storybook:build first.

Adding New Tests

Visual testing is run against the stories in Storybook, and stories added there need to be manaully added to test/visual/stories.js. Only stories that are listed there will be included in the visual regression, so please add any new stories you create to this list so that the quality of this library can be maintained over time.

Keeping CI Assets Up-to-date

If you find the visual-* jobs failing on CircleCI for reasons that you expect (you've updated the Spectrum CSS dependencies, you've added new tests, etc.) then you will need to update the golden images cache key before your build will pass. The first step to doing so is to review the test results available in the "Artifacts" tab in CircleCI. Before updating the cache key, be sure that the updated caches are both complete (there are times when process errors prevent images from being correctly created) and appear as expected. If you agree with the updated cache content, update the golden images cache key as follows.

Your failing branch will have created a new cache with a key of v1-golden-images-{{ .Revision }}-<< parameters.regression_color >>-<< parameters.regression_scale >>-{{ epoch }}. In .circleci/config.yml, you will use that to update the cache that is restored at the beginning of the run-regressions job. Using the revision number outlined in the Build Golden Images Revision Cache step of your failing build, update the current_golden_images_hash paramater that appears as follows:

parameters:
    current_golden_images_hash:
        type: string
        default: ${UPDATE_REVISION_NUMBER_HERE}

This will ensure that tests on this branch point to this cache key for at least the next 30 days (keep-alive time of caches on CircleCI). Once the branch is merged to main, a cache key of v2-golden-images-main-<< parameters.regression_color >>-<< parameters.regression_scale >>-<< parameters.regression_dir >>-{{ epoch }} will be created on each successful build of main that will be long-lived and act as the "fallback" once the revision keyed cache has expired.

Benchmarking

You can acquire current runtimes for the individual elements with:

yarn build:tests
yarn test:bench

This will run the defined Tachometer tests and report the current runtime cost of each individual element. When not making changes to the benchmarks thy have been built on your local machine, you can stip yarn build:tests for later passes.

Anatomy of a Component

There is extended documentation on adding a new component to the library in the documentation site. However, at a high level, you will be building the following structure:

packages
- new-component-name
  - src
    - index.ts
    - new-component-name.css
    - new-component-name.ts
    - spectrum-config.js
    - spectrum-new-component-name.css
  - stories
    - new-component-name.stories.ts
  - test
    - benchmark
      - test-basic.ts
    - new-component-name.test.ts
  - package.json
  - README.md
  - tsconfig.json

For a list of component waiting to be implemented, visit our missing components tag.

Development within Adobe

Due to the internal @adobe npm registry served by Artifactory, when developing this module internally it is necessary to provide an .npmrc local to this project which forces the use of the public @adobe scope on public npm. Therefore if you are an Adobe employee working on this project add the following to a .npmrc file in this folder:

@adobe:registry=https://registry.npmjs.org/
registry=https://registry.npmjs.org/

This will ensure that when installing dependencies you do not accidentally pull from the internal repositories.

IDE Notes

The build process compiles .css files using PostCSS and wraps them in the lit-html css template tag and writes out a .css.ts file for easy import into TypeScript files. This file should not be edited, and is ignored by .gitignore, but you may also wish to hide the files in your IDE.