Hey there and thanks for stopping by! We welcome all feedback and contributions to Calcite Components. If you are interested in getting involved, we ask that you give our guidelines a read. Below is a list of things we've found work well for us as we continue developing our components.
Please see our contributing guidelines.
This project uses lint-staged to automatically format code on commit, making it easier to contribute.
We have created templates for new issues for everyone to follow for consistency. Please be specific and thorough when submitting new issues! Think about things like user stories, acceptance criteria, design, and any other details that might be helpful for developers and designers.
This project follows conventional commits, which are used to generate the changelog. Be sure to provide clear and sufficient information in commit messages. This is important because the commit messages are used to automatically update the changelog.
In order to ensure conventional commits are followed, pull requests will run a check to indicate whether the PR is following the convention or not. The Semantic Pull Request status check will ensure your pull requests are semantic before you merge them.
When submitting a pull request, please use one of the following formats for your branch name:
For pull requests associated with an existing issue:
<username>/<issue-id><issue-description>
johndoe/15-update-modal
johndoe/update-modal-15
For pull requests without an associated issue:
<username>/<issue-description>
johndoe/modal-styling
<username>/<type-of-pr><issue-description>
johndoe/docs/update-modal-docs
johndoe/feature/add-something-to-modal
For ease of discoverability, commit messages for breaking changes should use both the header (!) and body (BREAKING CHANGE:) syntax:
<type>!: <descriptive summary>
<optional info>
BREAKING CHANGE: <details about the change and migration options (this can span multiple lines)>
See the conventional commits doc for more helpful information.
We use GitHub issues to keep track of bugs. Please follow our bug issue template and explain the problem clearly for us maintainers to understand and reproduce. The more details the better!
Things to consider:
- Use a clear and descriptive title
- What is happening now vs what should happen?
- Tell us how to reproduce the issue (e.g. is it happening in a specific browser?)
- Can it be reliably reproduced? If not, tell us how often it happens and under what circumstances.
- Screenshots and GIFs are our friends!
- Did this problem start happening after a recent release or was it always a bug?
Our code base is written entirely in TypeScript and we should aim to have it that way. We have configured the project to help adhere to some conventions and formatting. Here are additional items to follow:
- Avoid using any as much as possible.
- Try to always provide a type.
- Provide JSDoc for all public APIs.
- Fix linting errors, don't ignore them.
Components must be accessible and are required to have tests that focus on a11y. We use the following resources as guides:
New components should have an issue so we can determine whether they belong here or calcite-components.
See the new component checklist.
This project uses Storybook to provide an interactive showcase of components with accompanying documentation.
For each main component (i.e., one that can be used by itself), there should be a <component-name>.stories.ts file in its component folder.
Each story should provide access to relevant knobs so users can test out different properties.
For additional documentation, create a usage folder in the component directory with a basic.md and optionally an advanced.md file (if additional documentation or examples are required) with snippets showing different supported use cases for the component.
The following resources showcase best practices we follow for our web components:
We follow Stencil's suggested component structure. See their style guide for more details.
Be sure to set shadow: true in Stencil's @Component options to make sure styles are encapsulated in our Calcite design system. This helps keep our components consistent across applications.
Many times it is necessary for components to have an id="something" attribute for things like <label> and various aria-* properties. To safely generate a unique id for a component, but to also allow a user supplied id attribute to work, follow the pattern using guid in our calcite-value-list.
This will create a unique id attribute like id="calcite-example-51af-0941-54ae-22c14d441beb", which should have a VERY low collision change since guid() generates IDs with window.crypto.getRandomValues. If a user supplies an id, it will respect the users id.
Components should require as a few text translations as possible. In general, this allows users to supply text values via slots and attributes and handle translations within their apps.
If your component involves formatting numbers or dates use the Intl APIs for formatting.
To add RTL support to your components, use the internal getElementDir helper to apply the dir attribute to the component. That way, the dir attribute of the component will always match that of the document. See use of getElementDir in calcite-panel.
Direction specific CSS can be implemented with CSS variables- see example here.
- https://medium.com/stencil-tricks/implementing-internationalisation-i18n-with-stencil-5e6559554117 and https://codesandbox.io/s/43pmx55vo9
- ionic-team/ionic-stencil-conference-app#69
Components should have an automated test for any incoming features or bug fixes. Make sure all tests pass as PRs will not be allowed to merge if there is a single test failure.
We encourage writing expressive test cases and code that indicates intent. Use comments sparingly when the aforementioned can't be fully achieved. Keep it clean!
Please see Stencil's doc for more info on end-to-end testing. See one of our test examples here.
See our README.md for a list of supported browsers.
- See our gotchas wiki for issues we've found with Stencil.