npm package: @heartlandone/vega-bootstrap
Description: Vega-bootstrap is mainly for auto-generating simple app component with/without framework specification built with vega component
Latest version: 0.1.2

# Vega Bootstrap

## Table of Contents
- [Introduction](#introduction)
- [High level workflow diagram](#high-level-workflow-diagram)
- [Get started](#get-started)
    * [Pre-requisite](#pre-requisite)
    * [How to create the input](#how-to-create-the-input)
    * [How to run it](#how-to-run-it)
        + [Watch the input config change and auto generate the output:](#watch-the-input-config-change-and-auto-generate-the-output-)
    * [Symlink with existing app for testing](#symlink-with-existing-app-for-testing)
- [TODOs:](#todos-)

## Introduction 
![demo gif](./docs/demo.gif)

Vega bootstrap is a tool targeting for generating stand-alone, framework-facing Vega component based module that you can import into your app component to run.

It avoids the similar effort you would have to create the same app component structure built on top of Vega Component for different frameworks (vanillaJs, Angular, etc.).

And if you want to update the component view/state/action, you can simply modify the input config and rebuild it and then the app component output for all the specified frameworks will be updated automatically.

## High level workflow diagram
![vega bootstrap workflow diagram](./docs/vega-bootstrap.drawio.svg) 
> created by draw.io, see [original file](./docs/vega-bootstrap.drawio) 

## Get started
### Pre-requisite
```bash
> yarn install
```

### How to create the input
The only thing you need to have is defining the `typescript` file for component input config, which might looks like:
```typescript
// my-component.input.ts
import { ComponentInput } from '../src/types/component/component.type';

const MyComponentInput: ComponentInput = {
    name: 'MyComponent',
    view: {
        viewNodes: [
           // view nodes to composite your app view
        ],
    },
    state: {
        stateNodes: [
            // state nodes to maintain your app state 
        ],
    },
    action: {
        actionNodes: [
            // action nodes to control your app view/state
        ],
    },
};

export default MyComponentInput;
```

This component input ts file will be the source of truth and vega-bootstrap will generate the framework specific component output based on this input config.

**Note: due to [a known issue from typescript](https://github.com/microsoft/TypeScript/issues/47935), for now the type of object nested property cannot not be recognized by typescript server, hence if you want to make use of the type hint by TS, you need to explicitly declare the property type like:**
```typescript
{
    // ...
    view: {
        viewNodes: [
            {
                type: 'vega-flex',
            } as ComponentViewNode,
        ]
    }
    // ...
}
```

### How to run it
To run the vega-bootstrap, simply run 
```bash
> yarn run build -c <input_config_path> -vanilla <vanilla_js_output_path> -angular <angular_output_path>
```

**Note: if you need help for the cli parameters, please run `yarn run help`**

an example will be:
```bash
> yarn run build -c ./input/simple-component.input.ts -vanilla ./output/vanilla-js -angular ./output/angular
```

#### Watch the input config change and auto generate the output:
vega-bootstrap also supports file watch, just simple run `build` script with `-w` option passed in  
```bash
> yarn run build -c ... -w
```

It will auto generate the output once the file change detected in component input config file

### Symlink with existing app for testing
You can either change the output folder path by changing the cli input or setup symlink by using `ln -s` to dynamically link the output to your project.

For example, to link the ESS output to `tiger/vega-playground/vega-angular-hello-world/src/app`, you can run
```bash
> cd tiger/vega-playground/vega-angular-hello-world/src/app
> ln -s ../../../../vega-bootstrap/output/angular/ESS ESS
```
And you should be able to see in `tiger/vega-playground/vega-angular-hello-world/src/app`
```bash
lrwxr-xr-x  1 zheng.yuan  1152374831    45B Mar 18 22:44 ESS -> ../../../../vega-bootstrap/output/angular/ESS
...
```
And then in the `app.module.ts`, import the linked component:
```ts
import { EssHomePage } from './ESS/ess-home-page';

@NgModule({
  declarations: [
      AppComponent, 
      EssHomePage // => import this component
  ],
  //...
})
export class AppModule {}
```

and then you can use it in `app.component.html` like below:
```angular2html
<ess-home-page></ess-home-page>
```


## TODOs:
* React support
* Vue support