This repo has two sites:
- The catalog site built with Batfish.
- The catalog contains examples of most common uses for each component and lists all available properties.
- To make sure all our components are production ready with Batfish, CI runs the
npm run build-docs
. - Every catalog example must have a test case.
- The test cases app available locally.
- The test cases app builds a local development site and snapshot tests for each component. The test cases app also includes less common use cases.
To run the catalog site at https://mapbox.github.io/dr-ui/:
npm run start-docs
To build the test cases app:
npm start
To run the tests:
npm test
To test local changes to dr-ui in a documentation site, use npx link
:
- Build dr-ui with
npm run build
. The/pkg
directory will be populated with the built files. - From the root of the consuming documentation site, run
npx link ../dr-ui/pkg
(this assumes the docs site and dr-ui share the same parent directory). - Start the development server on the consuming docs site:
npm start
. You should see any dr-ui changes that were built in step 1. - After making changes to dr-ui, save and build (step 1). The changes will be available when the consuming site is reloaded.
Every component should have a __tests__
directory with the following files:
/[component-name]-test-cases.js
. The*test-cases.js
file includes variations of the component to demonstrate different capabilities and properties for the component. Every catalog example must have a test case./[component-name].test.js
. The*.test.js
file should create a unit test for each test case found in*test-cases.js
.
Run the new
command to generate all the files and starter code to create a new component. The command accepts an argument with the name of the component:
node scripts/new.js Button
node scripts/new.js responsive button
The command will create the following folder structure:
src/components/[component-name]/
index.js
[component-name].js
examples/
basic.js
__tests__/
[component-name]-test-cases.js
[component-name].test.js
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.
Once all changes are on the main branch, follow these steps:
- Update CHANGELOG.md with a commit like "Prepare vX.X.X"
- From the
main
branch, make sure you pulled the latest. - Run
npm version <major|minor|patch>
to increment the version number in package.json and package-lock.json. This will automatically create a commit and tag for the release. - Push your commit.
- Run
npm ci
and thennpm run build
. - Run
cd pkg/
to change into the pkg directory and then publish the new version on npm:mbx npm publish
. cd
back to the root directory and runnpm run deploy-docs
to deploy the catalog site.
A new release needs to be deployed on the various docs sites that consume dr-ui
. Two scripts have been configured to perform this task. Both scripts do the same task, so please choose one option and run that only.
scripts/create-pull-request.sh
includes a sequence of shell commands to navigate to a docs repo on your local dev environment, run npm install @mapbox/dr-ui
to install a specific version of dr-ui
, commit package.json
and package.lock
to a new branch, and create a github pull request.
This script should be run from the root of this repository, and requires you to have github cli installed.
To use:
- Authenticate with github cli by running
gh login
- From the root of this repository, run
sh scripts/create-pull-request.sh [dr-ui version] [docs-repo]
docs-repo
is the name of the directory for a docs repo that is already cloned to your local environment and is in the same directory as this repository.
Example: sh scripts/create-pull-request.sh 5.1.12 mapbox-gl-js-docs
Repeat for all docs sites that need the update, and merge PRs through your normal workflow.
scripts/update-dr-ui-all.sh
, iterates over the repositories listed in scripts/target-repositories.json
and runs create-pull-request.sh
for each one. Make sure you have each of the target repositories cloned to your local machine.
This script should be run from the root of this repository, and requires you to have github cli installed.
To use:
- Authenticate with github cli by running
gh login
- From the root of this repository, run
sh scripts/update-dr-ui-all.sh [dr-ui version]
Example: sh scripts/update-dr-ui-all.sh 5.1.12