resin-cli-visuals

resin-cli-visuals
-----------------


Join our online chat at 

Resin CLI UI widgets.

Role
----

The intention of this module is to provide a collection of command line widgets to be used by the Resin CLI and its plugins.

Installation
------------

Install resin-cli-visuals by running:

``sh
$ npm install --save resin-cli-visuals
`

Documentation
-------------

Classes

DriveScanner

Objects

visuals : object

DriveScanner

Kind: global class
Summary: Dynamically detect changes of connected drives
Access: protected

* DriveScanner
* [new DriveScanner(driveFinder, [options])](#new_DriveScanner_new)
* .stop()

$3

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| driveFinder | function | | drive finder |
| [options] | Object | | scan options |
| [options.interval] | Number | 1000 | interval |
| [options.drives] | Array.<Object> | | current drives |

Example
`js
scanner = new DriveScanner driveFinder,
interval: 1000
drives: [
{ foo: 'bar' }
]
`


$3


Kind: instance method of DriveScanner
Summary: Stop the interval
Access: public
Example
`js
scanner = new DriveScanner(@driveFinder, interval: 1000)
scanner.stop()
`

visuals : object

Kind: global namespace

* visuals : object
* .Spinner
* new Spinner(message)
* .start()
* .stop()
* .Progress
* new Progress(message)
* .update(state)
* .SpinnerPromise
* new SpinnerPromise(options)
* .table : object
* .horizontal(data, ordering)
* .vertical(data, ordering)
* [.drive([message])](#visuals.drive) ⇒ Promise.<String>

$3

Kind: static class of visuals
Summary: Create a CLI Spinner
Access: public

* .Spinner
* new Spinner(message)
* .start()
* .stop()

#### new Spinner(message)
Returns: Spinner - spinner instance
Throws:

- Will throw if no message.

| Param | Type | Description |
| --- | --- | --- |
| message | String | message |

Example
`js
spinner = new visuals.Spinner('Hello World')
`


#### spinner.start()
Kind: instance method of Spinner
Summary: Start the spinner
Access: public
Example
`js
spinner = new visuals.Spinner('Hello World')
spinner.start()
`


#### spinner.stop()
Kind: instance method of Spinner
Summary: Stop the spinner
Access: public
Example
`js
spinner = new visuals.Spinner('Hello World')
spinner.stop()
`


$3

Kind: static class of visuals
Summary: Create a CLI Progress Bar
Access: public

* .Progress
* new Progress(message)
* .update(state)

#### new Progress(message)
Returns: Progress - progress bar instance
Throws:

- Will throw if no message.

| Param | Type | Description |
| --- | --- | --- |
| message | String | message |

Example
`js
progress = new visuals.Progress('Hello World')
`


#### progress.update(state)
Kind: instance method of Progress
Summary: Update the progress bar
Access: public
Parm: String [state.message] - message

| Param | Type | Description |
| --- | --- | --- |
| state | Object | progress state |
| state.percentage | Number | percentage |
| [state.eta] | Number | eta in seconds |

Example
`js
progress = new visuals.Progress('Hello World')
progress.update(percentage: 49, eta: 300)
`


$3

Kind: static class of visuals
Summary: Create a CLI Spinner that spins on a promise
Access: public
Fulfil: Object value - resolved or rejected promise

#### new SpinnerPromise(options)
This function will start a Spinner and stop it when the
passed promise is either fulfilled or rejected. The function
returns the passed promise which will be in either rejected or
resolved state.

| Param | Type | Description |
| --- | --- | --- |
| options | Object | spinner promise options |
| options.promise | Promise | promise to spin upon |
| options.startMessage | String | start spinner message |
| options.stopMessage | String | stop spinner message |

Example
`js
visuals.SpinnerPromise
promise: scanDevicesPromise
startMessage: "Scanning devices"
stopMessage: "Scanned devices"
.then (devices) ->
console.log devices
`


$3

Kind: static namespace of visuals

* .table : object
* .horizontal(data, ordering)
* .vertical(data, ordering)

#### table.horizontal(data, ordering)
Notice that you can rename columns by using the CURRENT => NEW syntax in the ordering configuration.

Kind: static method of table
Summary: Make an horizontal table
Access: public

| Param | Type | Description |
| --- | --- | --- |
| data | Array.<Object> | table data |
| ordering | Array.<String> | display ordering |

Example
`js
console.log visuals.table.horizontal [
{ name: 'John Doe', age: 40 }
{ name: 'Jane Doe', age: 35 }
], [
'name => full name'
'age'
]

FULL NAME AGE
John Doe 40
Jane Doe 35
`


#### table.vertical(data, ordering)
Notice that you can rename columns by using the CURRENT => NEW syntax in the ordering configuration.

Vertical tables also accept separators and subtitles, which are represented in the ordering configuration as empty strings and strings surrounded by dollar signs respectively.

Kind: static method of table
Summary: Make a vertical table
Access: public

| Param | Type | Description |
| --- | --- | --- |
| data | Object | table data |
| ordering | Array.<String> | display ordering |

Example
`js
console.log visuals.table.vertical
name: 'John Doe'
age: 40
job: 'Developer'
, [
'$summary$'
'name => full name'
'age'
''
'$extras$'
'job'
]

== SUMMARY
FULL NAME: John Doe
AGE: 40

== EXTRAS
JOB: Developer
`


$3

The dropdown detects and autorefreshes itself when the drive list changes.

Kind: static method of visuals
Summary: Prompt the user to select a drive device
Returns: Promise.<String> - device path
Access: public

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [message] | String | 'Select a drive' | message |

Example
`js
visuals.drive('Please select a drive').then (drive) ->
console.log(drive)
`

Support
-------

If you're having any problem, please raise an issue on GitHub and the Resin.io team will be happy to help.

Tests
-----

Run the test suite by doing:

`sh
$ gulp test
`

Contribute
----------

- Issue Tracker: github.com/resin-io/resin-cli-visuals/issues
- Source Code: github.com/resin-io/resin-cli-visuals

Before submitting a PR, please make sure that you include tests, and that coffeelint runs without any warning:

`sh
$ gulp lint
``

License
-------

The project is licensed under the Apache 2.0 license.