# @borderlessvr/essentials > UI components for Borderless' React Apps Latest version **0.1.5** (published 2023-10-12) · Unlicensed license · 0 weekly downloads ## Install ```sh npm install @borderlessvr/essentials pnpm add @borderlessvr/essentials yarn add @borderlessvr/essentials bun add @borderlessvr/essentials ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.1.5 | | Published | 2023-10-12 | | First published | 2022-10-25 | | Weekly downloads | 0 | | License | Unlicensed | | TypeScript types | none | | Module format | CommonJS | | Node | >=16.0.0 | | Dependencies | 3 | | Unpacked size | 1.7 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Valerie Kraucunas | | Maintainers | dave-bvr, valerie-bvr, sam-bvr, jonan-bvr, borderlessexperiences | | Keywords | ui, kit, components | ## Links - npm: https://www.npmjs.com/package/@borderlessvr/essentials - Repository: https://github.com/borderlessvr/essentials - Homepage: https://github.com/borderlessvr/essentials#readme - Issues: https://github.com/borderlessvr/essentials/issues - npm.io page: https://npm.io/package/@borderlessvr/essentials ## Dependencies (3) - [react](https://npm.io/package/react.md) ^18.2.0 - [react-dom](https://npm.io/package/react-dom.md) ^18.2.0 - [prop-types](https://npm.io/package/prop-types.md) ^15.8.1 ## Alternatives - [@progress/kendo-ooxml](https://npm.io/package/@progress/kendo-ooxml.md) — 152.1K weekly downloads - [@progress/kendo-react-ripple](https://npm.io/package/@progress/kendo-react-ripple.md) — 8.0K weekly downloads - [@progress/kendo-react-orgchart](https://npm.io/package/@progress/kendo-react-orgchart.md) — 4.3K weekly downloads - [@praxisui/dynamic-fields](https://npm.io/package/@praxisui/dynamic-fields.md) — 2.4K weekly downloads - [@progress/kendo-vue-listbox](https://npm.io/package/@progress/kendo-vue-listbox.md) — 932 weekly downloads ## Recent versions - 0.1.5 (latest) — 2023-10-12 - 0.1.4 — 2023-08-16 - 0.1.3 — 2023-06-22 - 0.1.2 — 2023-05-01 - 0.1.1 — 2023-01-11 - 0.1.0 — 2023-01-11 - 0.0.9 — 2022-12-19 - 0.0.8 — 2022-12-06 - 0.0.7 — 2022-11-23 - 0.0.6 — 2022-11-17 - 0.0.5 — 2022-11-17 - 0.0.4 — 2022-11-17 - 0.0.3 — 2022-11-16 - 0.0.2 — 2022-11-16 - 0.0.1 — 2022-10-25 ## README # Borderless Essentials [![version-v0.1.5](https://img.shields.io/badge/version-v0.1.5-teal.svg)](https://github.com/borderlessvr/essentials/tree/main) ## 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 ```scss /* 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` --- _Source: https://npm.io/package/@borderlessvr/essentials · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._