import { Meta } from "@storybook/addon-docs/blocks";

<Meta title="Contributing Guide/Guide/Create-Edit Component" />

<style>{`
  a {
    color: #5ECE7B !important;
  }

  .alert {
    background: #efeded;
    padding: 1rem;
    margin: 0.5rem 0 1rem;
  }

  .tip {
    border-left: 5px solid #5ECE7B;
  }

	.warning {
		border-left: 5px solid #ffc107;
		background-color: #fff4d5;
	}

  .danger {
    border-left: 5px solid #c00;
		background-color: #ffe6e6;
  }

  .danger * {
    color: #4d0000;
  }
`}</style>

# How to create/edit Storefront UI component

At this point we assume you're already familiar with [our coding guidelines](?path=/story/introduction-contributing-guide-code-guidelines--page) and know how to [work with our Figma designs](?path=/story/introduction-design-principles--page#working-with-figma). The below section will guide you through how to create your first component for the library!

## Generate the component's template

Run `create-component` script at the respository's root level to generate all the files needed.

```bash
$storefront-ui yarn run create-component
```

You will need to select the correct configurations for your component, such as:

1. **Framework** (at the moment we only have Vue.js)
2. Which **group directory** this component belongs to - according to [Atomic Design](http://bradfrost.com/blog/post/atomic-web-design/) and from the component's requirements.
3. **Name** of the component (**WITHOUT** the prefix `Sf`)

Once done, it will generate boilerplates and help you create a component in standardized way without a lot of effort.

- All the files **except** `.scss` will be located in `packages/vue/src/components/{group-type}/{Sf<ComponentName>/}`.
- The `scss` file will automatically reside in `packages/shared/styles/components/` directory.

## Create proper markup

Start with creating a proper CSS/HTML markup without worrying about the slots and SCSS variables.
Once you have semantical-correct and good-looking component, it's time to make it customizable.

### Make the content customizable with slots

Now it's time to figure out which content should be customizable.
By design try **not** to pass any content into `props` - instead use `slots`.

<div class="alert tip">

Every **text field** should be a `slot`. Take a look at [SfBanner](https://github.com/DivanteLtd/storefront-ui/blob/master/packages/vue/src/components/molecules/SfBanner/SfBanner.vue)
component for inspiration.

</div>

## Edit styles

<div class="alert warning">

You should read and follow our [CSS Coding guidelines](?path=/story/introduction-contributing-guide-code-guidelines--page#css-rules).

</div>

For color modifiers (_if it's applied to your component_)
you should use common classes, by the following convention:
`color-primary`, `color-secondary`, `color-info`, `color-success`,
`color-warning`, `color-danger`.

We already have these color helpers declared globally, and it may
work by default for your component. In this case you should just add
these classes as `CSS Modifier` on your component documentation,
without adding new styles for that.

Example: [SfButton](https://github.com/DivanteLtd/storefront-ui/blob/master/packages/vue/src/components/atoms/SfButton/SfButton.stories.js)

## Add unit tests

Please follow [our Unit tests guidelines](?path=/story/introduction-contributing-guide-code-guidelines--page#unit-tests)

Some of the most common cases can be found in an [example template](https://github.com/DivanteLtd/storefront-ui/blob/master/packages/vue/scripts/component-template/component.spec.js).

## Documentation and stories

Document the components according to
[documentation template](https://github.com/DivanteLtd/storefront-ui/blob/master/packages/vue/scripts/component-template/component.stories.js)
in `packages/vue/scripts/component-template` folder.

## Running tests

You should test your component by importing it inside `packages/vue/src/Playground.vue`,
then running `yarn run serve`.

Or do `yarn test:unit` to run all the unit tests.

## Export components

Add your components code in:

- `packages/vue/js.js` (JS part);
- `packages/vue/html.js` (Template part);
- `packages/vue/index.js` (SfComponent);