@borderlessvr/essentials

Borderless Essentials

Getting Started: Consumer mode

npm i @borderlessvr/essentials

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

1. 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

1. Fonts and common typography mixins
2. Workhorse elements
   1. BvrButton
   2. Card
   3. Form elements
   4. Modal
3. 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
4. Logo
5. 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?

1. 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
2. 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"
3. 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