|
| 1 | +--- |
| 2 | +applyTo: '**/*' |
| 3 | +--- |
| 4 | + |
| 5 | +# Basics |
| 6 | + |
| 7 | +- `Mrv2` is the abbreviation for `momentum-react-v2` |
| 8 | +- `momentum-react-v2` is a React component library using TypeScript |
| 9 | +- `momentum-react-v2` is a Shim Layer for React components from NPM package `@momentum-design/components/dist/react` |
| 10 | +- Components in the folder `src/components/` are the new components that are supposed to be maintained and used. |
| 11 | +- Components in the folder `src/legacy/` are the old components that are deprecated and should not be used in new code. |
| 12 | + |
| 13 | +# Project coding standards |
| 14 | + |
| 15 | +## General Guidelines |
| 16 | + |
| 17 | +- Don't generate unnecessary code comments, comments are only necessary for complex bits of code |
| 18 | +- Always add a comment, 'Start AI-Assisted' at the top of any generated code |
| 19 | +- Always add a comment, 'End AI-Assisted' at the bottom of any generated code |
| 20 | +- All domains, URLs, hosts, DNS, etc must be configurable, or have a graceful fallback |
| 21 | +- Don't ever respond with an inability to produce output, always try to produce something |
| 22 | + |
| 23 | +## Bundling Guidelines |
| 24 | + |
| 25 | +- We use TSC for compiling & bundling our application, so when responding about build tools, always give me instructions and code samples that use TSC |
| 26 | + |
| 27 | +## TypeScript Guidelines |
| 28 | + |
| 29 | +- We prefer Typescript over Javascript |
| 30 | +- Use Typescript for all new code, all pre-existing Javascript edits can remain as Javascript |
| 31 | +- Use optional chaining (?.) and nullish coalescing (??) operators |
| 32 | +- Prefer type imports over plain imports when importing type declarations |
| 33 | + |
| 34 | +## React Guidelines |
| 35 | + |
| 36 | +- Use functional components with hooks |
| 37 | +- Follow the React hooks rules (no conditional hooks) |
| 38 | +- Use SASS for component styling as an *.style.scss file (refer to other components as an example) |
| 39 | +- Rendering conditional classNames should done only through the use of the classnames library |
| 40 | +- Always prefer using existing components from the `@momentum-design/components/dist/react` package, instead of creating new code for common UI elements like buttons, inputs, etc. |
| 41 | +- When using components from `@momentum-design/components/dist/react` package, alias them to `Mdc` in your imports, e.g. `import { Button as MdcButton } from '@momentum-design/components/dist/react'` |
| 42 | + |
| 43 | +### React Component Folder Structure |
| 44 | + |
| 45 | +Follow the component structure guidelines below as defined in the plop config templates here @file:config/plop/plop-templates/component/\*_/_ |
| 46 | + |
| 47 | +``` |
| 48 | +src/components/ComponentName/ |
| 49 | +├── ComponentName.tsx # Main component implementation |
| 50 | +├── ComponentName.style.scss # Styling with SASS |
| 51 | +├── ComponentName.unit.test.tsx # Component tests, using RTL |
| 52 | +├── ComponentName.types.ts # TypeScript interfaces and types |
| 53 | +├── ComponentName.constants.ts # Constants used by the component |
| 54 | +├── ComponentName.stories.tsx # Storybook stories |
| 55 | +├── ComponentName.stories.args.ts # Storybook arg definitions |
| 56 | +├── ComponentName.stories.docs.mdx # Storybook docs description |
| 57 | +└── index.ts # Export file |
| 58 | +``` |
| 59 | + |
| 60 | +### Component File |
| 61 | +- Use a `ComponentName.tsx` file for the main component implementation. |
| 62 | +- Import the React components from `@momentum-design/components/dist/react` only and alias them to `MdcComponentName` in the import. |
| 63 | + |
| 64 | +### Types File |
| 65 | +- Use a `ComponentName.types.ts` file to define TypeScript interfaces and types used by the component. |
| 66 | +- Use the `PascalCase` naming convention for interfaces and type aliases. |
| 67 | +- `ComponentNameProps` should be the name of the main interface for the component's props. |
| 68 | +- `ComponentNameProps` should extend the type from `MdcComponentNameProps` if the component is based on a Momentum Design component. |
| 69 | + |
| 70 | +### Constants File |
| 71 | +- Use a `ComponentName.constants.ts` file to define constants used by the component. |
| 72 | +- Use the `ALL_CAPS` naming convention for constants. |
| 73 | +- Constants should always be exported from the constants file like so: |
| 74 | +```typescript |
| 75 | +const CLASS_PREFIX = 'md-component-name'; |
| 76 | + |
| 77 | +const DEFAULTS = { |
| 78 | +}; |
| 79 | + |
| 80 | +const STYLE = { |
| 81 | + wrapper: `${CLASS_PREFIX}-wrapper`, |
| 82 | +}; |
| 83 | + |
| 84 | +export { CLASS_PREFIX, DEFAULTS, STYLE }; |
| 85 | +``` |
| 86 | + |
| 87 | +## Testing |
| 88 | + |
| 89 | +- Testing for components use the `React Testing Library` library (do not use Enzyme!). |
| 90 | +- Testing interactions with the `user-event` library (@testing-library/user-event). |
| 91 | +- For rendering components in tests, always use the `renderWithWebComponent` utility function (@file:test/utils.ts). |
| 92 | + |
| 93 | +## Naming Conventions |
| 94 | + |
| 95 | +- Use PascalCase for component names, interfaces, and type aliases |
| 96 | +- Use camelCase for variables, functions, and methods |
| 97 | +- Use ALL_CAPS for constants |
| 98 | + |
| 99 | +## CSS and SASS Guidelines |
| 100 | + |
| 101 | +- Use rem instead of px |
| 102 | +- Only the new CSS vars for colours should be used, such as: `var(--mds-<...Example>:var(--mds-color-theme-common-text-success-normal` |
0 commit comments