npm package: @skilld/drupal-component-generator
Description: Drupal component generator
Author: Skilld
Latest version: 1.0.6

<p align="center">
  <a href="https://skilld.cloud/" target="_blank">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/skilld-labs/drupal-component-generator/logo/dark.svg">
      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/skilld-labs/drupal-component-generator/logo/light.svg">
      <img alt="Logo" src="https://raw.githubusercontent.com/skilld-labs/drupal-component-generator/logo/light.svg" width="360" height="108" style="max-width: 100%;">
    </picture>
  </a>
</p>
<p align="center">
  This is a sub-package of <a href="https://www.npmjs.com/package/@skilld/drupal-theme-generator">Drupal theme generator</a> and it will help you to generate theme component.
</p>

#### Navigation
- [Installation](#installation)
- [Files structure](#files-structure)
- - [css](#css)
- - [js](#js)
- - [twig](#twig)
- - [stories.js](#storiesjs)
- - [yml](#yml)
- [License](#license)

## Installation

Run from generated theme `yarn cc` or via docker `make cc`. Component generator is smart, so it will ask you several questions in console
once you have executed one of those commands. Once script execution is finished - you will find your newly created component in
`templates/components/[type of integration]/` folder.

If you don't understand how your component will be integrated in Drupal - just select `uncategorized` option in console during
generation.

## Files structure

After generation you will have a new folder with the name of your component and prefix of atomic type. Inside this folder you will
get 7 generated files.

### css

For writing styles of your component - you have to use `*.src.css` filename. Put styles in there and after compilation your styles
will be compiled into `*.css` file <- use this compiled file in Drupal.

It's recommended to use [BEM methodology](https://getbem.com/naming/) of writing styles. Also you can use drupal's breakpoints in CSS,
see [here](https://www.npmjs.com/package/@skilld/drupal-theme-generator#drupals-breakpoints-in-css-and-js) how to do that.

If you need images in CSS - put them into `your-component-name/images` folder and call normally from CSS like this for example:

`background-image: url('./images/name-of-image.jpg);`

### js

For writing scripts - you have to use `*.src.js` filename. Compiled version is `*.js`. You have to use compiled file in Drupal.

By default your generated `*.src.js` will have Drupal behaviors on the board. Use `context` and / or `settings` normally in `attach` method
according to Drupal specification. Behaviors are working in Storybook. There is also `once` function available.

Behavior name is unique and will never have collisions with other behaviors. It consist of:

`behaviors.[ThemeName][AtomicType][NameOfComponent]`

### twig

Twig file is based on javascript implementation of Twig PHP (thanks to [twig.js](https://www.npmjs.com/package/twig)).
All the available Drupal's functions and filters are available and works same way in Storybook. So write 
any required markup and enjoy its display in Storybook.

A component should have only one twig file inside. This file is automatically grabbed by Storybook - you don't need to write
an extra code to connect twig in story - it's already done by component generator template.

### stories.js

File required by Storybook. It will help you to configure your story: setup test content, declare argTypes, modifiers,
some specific behaviors of your component, and so on.

This file normally contains already everything you will potentially need for any possible case.

- Use `faker` if you would like to generate fake content (it's already imported by default in `*.stories.js` file), so just call it.
- If you need to generate Drupal's attributes, use `const some_custom_attributes = new DrupalAttribute();` in your story. By the way
`attributes` variable is always available in any twig by default.
- For specific effects in your story use `useEffect` - just uncomment it in `BasicRender` function.
- If you need fullscreen component - uncomment property `fullscreen`
- If you don't need white background (which is default in story) - uncomment `backgrounds` property and your background will be grey.
- If you need to set custom `argTypes` - just uncomment it. By the way - all `settings` from `*.yml` file are automatically
added into `argTypes`.

If you want to call any component from any other component, use the following:

```
r('[atomic type]-[component name]', [args]);
```

For example: 

```
r('a-icon', {
  icon: 'calendar'
})
```

By default render function will search for `Basic` story. If you don't have `Basic` story or want to call
another story of the component, use the following:

```
r(['[atomic type]-[component name]', '[story name]'], [args]);
```

For example:

```
r(['m-card', 'Second'], {
  title: 'My title',
})
```
 
### yml

This is the main file required by our integration with Drupal. But also it's required by `Storybook`.

Based on type of integration, `yml` file should also have prefix with type of integration in its filename. Available types of integration are: `theme` for layouts or as a theme hook integration, 
`suggestion` and `ui_patterns`. If your component isn't integrated - it shouldn't have any prefix in filename.

Structure of this file is based on [UI Patterns](https://ui-patterns.readthedocs.io/en/8.x-1.x/content/patterns-definition.html)

You should always have in this file:
- `use` setting with path to `twig` of component
- `label` setting for Preview
- optional libraries
- optional [settings](https://www.drupal.org/project/ui_patterns_settings)
- optional fields

`settings` in this file are automatically catched by Storybook and available as `argTypes` of component.

And another important thing is a one or two more lines describing type of integration of component in Drupal. These lines are:
- `hook theme`
- `base hook`

Read [here](https://www.drupal.org/project/component_connector) about our integration to understand.

## License

This project is licensed under the MIT open source license.