@mapbox/dr-ui

Pronounced "Doctor UI". Documentation React UI components. See @mapbox/mr-ui.

UI components for Mapbox documentation projects.

This project is for internal Mapbox usage. The code is open source and we appreciate bug reports; but we will only consider feature requests and pull requests from Mapbox developers.

Installation

npm install @mapbox/dr-ui

On Mapbox projects, pair these components with version 0.26.0 of Mapbox's custom Assembly build. (This is not in peerDependencies because you might use <link> and <script> tags instead of the npm package.)

The public Assembly build should work fine, with maybe one or two hiccups.

Usage

Import individual components! All components are exposed at @mapbox/dr-ui/{component-name}. For example:

import Card from '@mapbox/dr-ui/card';
import BackToTopButton from '@mapbox/dr-ui/back-to-top-button';

Only the component itself and whatever it depends on will be drawn into your bundle.

Development

Here are some commands you'll probably want to use:

# Start the test-cases app.
npm start
# Start the test-cases app, compatible with IE11 (removes Search component).
npm run start-legacy

Docs build process and automated testing coming soon.

When making changes to the build script, test that the module builds correctly by running npm run build and then linking the local package with another local repo. Make sure you are able to run the local repo without errors from dr-ui.

Tests

Each component should have a __tests__ folder with a component-name-test-cases.js and component-name.test.js. The *test-cases.js file should include variations of the component in use to demonstrate the different capabilities and properites for the component. The *.test.js file should create a unit test for each test case found in *test-cases.js.

Run the tests:

npm test

Update snapshots (run when making changes to *.test.js):

npm test -- -u

Publishing

The build command creates a pkg/ directory that contains the code we want to publish, organized the way we want it. So pkg/ is the directory that we publish. pkg/package.json is a clone of package.json but with private: true removed.

1. Document changes in the CHANGELOG.
2. Increment the version key in package.json and package-lock.json.
3. Make sure all this is committed, typically with a commit message like Prepare 0.0.11.
4. Create a tag. No message is necessary, since the changelog includes explanations of changes. For example: git tag -a 0.0.11 -m "".
5. Push the tag: git push --tags.
6. Push your commit.
7. Build the pkg/ directory: npm run build.
8. cd into the pkg/ directory and publish the new version on npm.