@borderlessvr/essentials NPM

Borderless Essentials

Getting Started: Consumer mode

npm i @borderlessvr/essentials

What's the best way to get acquainted with Essentials?

Colors
1. Learn what colors we offer
2. Learn the contextual color variables and use them whenever feasible in your code over the direct name of the raw color

  /* layout colors */
  --color-fg: app default text color
  --color-bg: the app background color level
  --color-surface: one layer up from background
  --color-surface-active: tertiary color of surface to use for active and hover states
  --color-border: common border color
  --color-primary: main accent color
  --color-secondary: secondary accent color

  /* status colors */
  --color-err: (red) color used for error text, icons, background colors and borders
  --color-warn: (orange) color used for warn scenarios icons, background colors and borders
  --color-validation: (green) color used for "valid" verification, success use-cases
  --color-info: (light blue) color used for non-status related notifications and iconography
  --color-disabled-bg: (grey) background color for disabled components/surfaces
  --color-disabled-fg: (grey) text color for disabled components

Fonts and common typography mixins
Workhorse elements
1. BvrButton
2. Card
3. Form elements
4. Modal
Common icons
1. IconX - also used as the plus
2. IconCheck
3. IconsModuleType - has the 4 icons for the types of modules, run via switch
Logo
Upcoming: Storybook documentation

Getting Started: Developer mode

git clone down the repo
npm install

Are you trying to run local dev in publisher while symlinked to essentials?

npm link HERE FIRST
npm link @borderlessvr/essentials wherever you're working

Creating a new component?

Clone the _template/ directory in components/ and update the names across the JSX and SCSS files
1. This will give you correct paths to style vars, the expected setup of PropTypes, etc
Please try to follow this flow when building JSX files
1. Imports, in correct order according to format on save settings of the linter
2. Docs
3. Component open
4. Props
  1. Nearly all components in Essentials will have a className prop at least, please do not remove it from the template code
  2. Heavily interactible components (form els) will often times have ...otherProps to ease unusual use-case scenarios
5. Top-level React hooks: useNavigation, useRef, etc
6. Local methods
  1. Common naming patterns: handleEvent wraps onEvent-like props to execute them, and any local to component actions
7. useEffect hooks, ordered as needed
  1. Don't forget useEffect is synchronous, so cascade them smart
8. return (markup)
9. PropTypes
  1. Please keep the any types limited
10. defaultProps
  1. For function props, always add a default console log call like "Forgot an onChange for the BvrButton"
Tests!
1. There are test coverage thresholds set on this repo. Please add something to the index.test.jsx that came with the template copy paste

Dev Standards

When working in Essentials please follow these guidelines

Git

Git flow feature-branching model for new work
Please git pull origin main on your feature branch(es) daily
Please git push at least once daily
CodeBranch naming strategy
- feat/: new features
- fix/: fixes
- chore/: used for version bumps, quick tasks for releases, etc
Preferred commit style
- fix:
- feat:
  - Try to only use for adding an atomic commit of a new feature
- style:
- docs:
- wip:

Workspace

Accept the recommended packages for VS Code. If you missed it, the list is in .vscode/extensions.json

Linting

We employ both ESLint and Stylelint
Prior to opening a PR, please run npm run lint:js and npm run lint:styles to be sure your code doesn't introduce inconsistencies to our codestyle

JS & JSX

ESLint formatOnSave is your friend
All JSX components require propTypes and defaultProps to be set up
- If you're unsure of the incoming shape, use any, it'll warn not error out
Always try to use non-destructive actions like .slice() and shallowClone from the project utils to create copies of lists and objects you're manipulating

Styles

There is a thorough order of attributes enforced by Stylelint, please enable formatOnSave for SCSS
Use rem over px, with the exception of 1px and 2px
Do not use em ever
Try to rely on margin-bottom over margin-top
Use padding to support internal size and margin for maintaining space away from other elements
Thinking about adding a color var to a component's SCSS? Maybe don't, check for an existing color, and then the "next closest" color already in the system before adding any 1-off colors

Release Process

NOTE: Do these steps after you've commited the last of the changes for your release

npm run lint:js && npm run lint:styles && npm test Address any errors before proceeding
Search project for current version number 0.0.x
Update README.md badge links
Update package.json version
Update CHANGELOG.md with overview of new material in the version (copy previous entry, update date, and Announcement and Changes fields)
npm i to update the package-lock.json
git add -A
git commit -m "chore: Release v0.0.x"
git tag -a v0.0.x -m "Release v0.0.x"
git push --follow-tags
Make sure that all passes, and is merged
npm publish