# Welcome to Cosmos!

Cosmos is a visual design system and UI component collection. Its goal is to empower application developers in their pursuit to create engaging and rewarding user experiences.

## Getting started

### Using Cosmos in your app

The recommended approach for using Cosmos is individual component imports to bundle with a method of your choosing.

```tsx
import ReactDOM from 'react-dom';
import { SomeComponent } from '@pega/cosmos-react-core';

ReactDOM.render(<SomeComponent {...props} />, el);
```

## Developing Cosmos components

Cosmos adheres to the following code style guides:

- Javascript: https://github.com/airbnb/javascript
- CSS: https://github.com/airbnb/css
- React(Followed loosely at the moment): https://github.com/airbnb/javascript/tree/master/react

These are enforced by [ESLint](https://eslint.org/), [Prettier](https://github.com/prettier/prettier) and [Stylelint](https://stylelint.io/) with settings some overridden/ignored. If you feel a certain coding style is better suited this project or should be allowed please speak up and advocate. Shoot for consistency and cleanliness.

With that, please take a moment to setup [Visual Studio Code](https://code.visualstudio.com/). We require the following extensions to be installed:

- [ESLint](vscode:extension/dbaeumer.vscode-eslint)
- [Prettier](vscode:extension/esbenp.prettier-vscode)
- [stylelint](vscode:extension/stylelint.vscode-stylelint)
- [cspell](vscode:extension/streetsidesoftware.code-spell-checker)
- [styled-components](vscode:extension/styled-components.vscode-styled-components)

Cosmos will check the format of your code and fail builds on linting errors so best to have your
[workspace in sync as you go](https://stackoverflow.com/questions/48363647/editorconfig-vs-eslint-vs-prettier-is-it-worthwhile-to-use-them-all). Next...

Clone Cosmos:

```bash
$ git clone https://github.com/pegasystems/cosmos-react.git
```

Install node_modules:

```bash
$ npm i
```

Start Cosmos dev server to run Storybook:

```bash
$ npm run start:stories
```

Create your first component - _Component names must capitalized, containing only letters_:

```bash
$ npm run create:component name:YourComponent [type:fn(default)|class|ref] [test:false(default)|true]
```

This cmd will generate a directory at /packages/cosmos-core/components/YourComponent/ with the following files:

1. **`YourComponent.tsx`** - A React component populated with some basic boilerplate
2. **`YourComponent.stories.tsx`** - A file used for the Storybook documentation that will hold demo components
3. **`YourComponent.test.ts`** - An empty file to use for test code, optional
4. **`index.ts`** - An index file that will re-export the default export from your component file

Inside **`YourComponent.tsx`** will be some initial boilerplate:

```ts
import { forwardRef, FunctionComponent, PropsWithoutRef, Ref } from 'react';
import styled from 'styled-components';

import { BaseProps, ForwardProps, PropsWithDefaults } from '../../types';
import { defaultThemeProp } from '../../theme';

export interface YourComponentProps extends BaseProps {
  ref?: Ref<HTMLDivElement>;
}

type YourComponentPropsWithDefaults = PropsWithDefaults<YourComponentProps>;

const StyledYourComponent = styled.div<YourComponentPropsWithDefaults>``;

StyledYourComponent.defaultProps = defaultThemeProp;

const YourComponent: FunctionComponent<YourComponentProps & ForwardProps> = forwardRef(
  (props: PropsWithoutRef<YourComponentProps>, ref: Ref<HTMLDivElement>) => {
    return <StyledYourComponent ref={ref} {...props} />;
  }
);

export default YourComponent;
```

The **`YourComponent.stories.tsx`** file will provide a hot reloading dev environment in Storybook:

```tsx
import YourComponent from './YourComponent';

// These are settings that storybook will use to render your component's stories
export default {
  title: 'Components/YourComponent',
  component: YourComponent
};

// This is the first story in your component's story book section
export const firstYourComponent = () => <YourComponent>Hello YourComponent</YourComponent>;
```