Skip to content

Commit b77b44a

Browse files
ghaiklorghaiklor
committed
feat(shape): Add API declaration to the package
1 parent a67fe7e commit b77b44a

File tree

2 files changed

+339
-0
lines changed

2 files changed

+339
-0
lines changed

‎API.md‎

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,337 @@
1+
<a name="Shape"></a>
2+
3+
## Shape
4+
Base class for creating other shapes.
5+
Each custom shape must extends from this class.
6+
7+
**Kind**: global class
8+
**Since**: 1.0.0
9+
10+
* [Shape](#Shape)
11+
* [new Shape(cursor, [options])](#new_Shape_new)
12+
* _instance_
13+
* [.get(path)](#Shape+get) ⇒ <code>\*</code>
14+
* [.set(path, value)](#Shape+set) ⇒ <code>[Shape](#Shape)</code>
15+
* [.getCursor()](#Shape+getCursor) ⇒ <code>Cursor</code>
16+
* [.setCursor(cursor)](#Shape+setCursor) ⇒ <code>[Shape](#Shape)</code>
17+
* [.getText()](#Shape+getText) ⇒ <code>String</code>
18+
* [.setText([text])](#Shape+setText) ⇒ <code>[Shape](#Shape)</code>
19+
* [.getWidth()](#Shape+getWidth) ⇒ <code>Number</code>
20+
* [.setWidth([width])](#Shape+setWidth) ⇒ <code>[Shape](#Shape)</code>
21+
* [.getHeight()](#Shape+getHeight) ⇒ <code>Number</code>
22+
* [.setHeight([height])](#Shape+setHeight) ⇒ <code>[Shape](#Shape)</code>
23+
* [.getX()](#Shape+getX) ⇒ <code>Number</code>
24+
* [.setX([x])](#Shape+setX) ⇒ <code>[Shape](#Shape)</code>
25+
* [.getY()](#Shape+getY) ⇒ <code>Number</code>
26+
* [.setY([y])](#Shape+setY) ⇒ <code>[Shape](#Shape)</code>
27+
* [.getBackground()](#Shape+getBackground) ⇒ <code>String</code> &#124; <code>Boolean</code>
28+
* [.setBackground([background])](#Shape+setBackground) ⇒ <code>[Shape](#Shape)</code>
29+
* [.getForeground()](#Shape+getForeground) ⇒ <code>String</code> &#124; <code>Boolean</code>
30+
* [.setForeground([foreground])](#Shape+setForeground) ⇒ <code>[Shape](#Shape)</code>
31+
* *[.render()](#Shape+render)*
32+
* [.toObject()](#Shape+toObject) ⇒ <code>Object</code>
33+
* [.toJSON()](#Shape+toJSON) ⇒ <code>JSON</code>
34+
* _static_
35+
* [.create(args)](#Shape.create) ⇒ <code>[Shape](#Shape)</code>
36+
* [.fromObject(obj, [cursor])](#Shape.fromObject) ⇒ <code>[Shape](#Shape)</code>
37+
* [.fromJSON(json, [cursor])](#Shape.fromJSON) ⇒ <code>[Shape](#Shape)</code>
38+
39+
<a name="new_Shape_new"></a>
40+
41+
### new Shape(cursor, [options])
42+
Create basic Shape instance.
43+
This shape renders nothing, but throws an exception that you need to implement this shape in childes.
44+
45+
46+
| Param | Type | Description |
47+
| --- | --- | --- |
48+
| cursor | <code>Cursor</code> | Cursor instance used for render the shape |
49+
| [options] | <code>Object</code> | Options object |
50+
| [options.text] | <code>String</code> | Text that will be rendered in the shape |
51+
| [options.width] | <code>Number</code> &#124; <code>String</code> | Shape width can be 100 (cells) or 100% |
52+
| [options.height] | <code>Number</code> &#124; <code>String</code> | Shape height can be 100 (cells) or 100% |
53+
| [options.x] | <code>Number</code> &#124; <code>String</code> | Absolute coordinate X can be 100 (cells), left, center, right or percents |
54+
| [options.y] | <code>Number</code> &#124; <code>String</code> | Absolute coordinate Y can be 100 (cells), top, middle, bottom or percents |
55+
| [options.background] | <code>String</code> &#124; <code>Boolean</code> | Background color can be color name, rgb, hex or false it you want to disable |
56+
| [options.foreground] | <code>String</code> &#124; <code>Boolean</code> | Foreground color can be color name, rgb, hex or false it you want to disable |
57+
58+
**Example**
59+
```js
60+
import Shape from 'kittik-shape-basic';
61+
62+
export default class Rectangle extends Shape {
63+
render() {
64+
const cursor = this.getCursor();
65+
// Implement your logic here for rendering the shape
66+
}
67+
}
68+
```
69+
<a name="Shape+get"></a>
70+
71+
### shape.get(path) ⇒ <code>\*</code>
72+
Get option value.
73+
74+
**Kind**: instance method of <code>[Shape](#Shape)</code>
75+
76+
| Param | Type | Description |
77+
| --- | --- | --- |
78+
| path | <code>String</code> | Path can be set with dot-notation |
79+
80+
**Example**
81+
```js
82+
shape.get('my.options.object.value');
83+
```
84+
<a name="Shape+set"></a>
85+
86+
### shape.set(path, value) ⇒ <code>[Shape](#Shape)</code>
87+
Set new option value.
88+
89+
**Kind**: instance method of <code>[Shape](#Shape)</code>
90+
91+
| Param | Type | Description |
92+
| --- | --- | --- |
93+
| path | <code>String</code> | Path can be set with dot-notation |
94+
| value | <code>\*</code> | Value that need to be written to the options object |
95+
96+
**Example**
97+
```js
98+
shape.set('my.options.object.value', 'value');
99+
```
100+
<a name="Shape+getCursor"></a>
101+
102+
### shape.getCursor() ⇒ <code>Cursor</code>
103+
Get cursor that used for render this shape.
104+
105+
**Kind**: instance method of <code>[Shape](#Shape)</code>
106+
<a name="Shape+setCursor"></a>
107+
108+
### shape.setCursor(cursor) ⇒ <code>[Shape](#Shape)</code>
109+
Assign cursor to the shape which will be used for render this shape.
110+
111+
**Kind**: instance method of <code>[Shape](#Shape)</code>
112+
113+
| Param | Type |
114+
| --- | --- |
115+
| cursor | <code>Cursor</code> |
116+
117+
<a name="Shape+getText"></a>
118+
119+
### shape.getText() ⇒ <code>String</code>
120+
Get text content from this shape.
121+
122+
**Kind**: instance method of <code>[Shape](#Shape)</code>
123+
<a name="Shape+setText"></a>
124+
125+
### shape.setText([text]) ⇒ <code>[Shape](#Shape)</code>
126+
Set new text content to this shape.
127+
128+
**Kind**: instance method of <code>[Shape](#Shape)</code>
129+
130+
| Param | Type | Default | Description |
131+
| --- | --- | --- | --- |
132+
| [text] | <code>String</code> | <code>&#x27;&#x27;</code> | New text |
133+
134+
<a name="Shape+getWidth"></a>
135+
136+
### shape.getWidth() ⇒ <code>Number</code>
137+
Get shape width.
138+
139+
**Kind**: instance method of <code>[Shape](#Shape)</code>
140+
<a name="Shape+setWidth"></a>
141+
142+
### shape.setWidth([width]) ⇒ <code>[Shape](#Shape)</code>
143+
Set new shape width.
144+
145+
**Kind**: instance method of <code>[Shape](#Shape)</code>
146+
147+
| Param | Type | Default | Description |
148+
| --- | --- | --- | --- |
149+
| [width] | <code>Number</code> &#124; <code>String</code> | <code>15</code> | Shape width |
150+
151+
**Example**
152+
```js
153+
shape.setWidth(15); // shape width is equal to 15 cells in the terminal
154+
shape.setWidth('20%'); // shape width is equal to 20% of total viewport width
155+
```
156+
<a name="Shape+getHeight"></a>
157+
158+
### shape.getHeight() ⇒ <code>Number</code>
159+
Get shape height.
160+
161+
**Kind**: instance method of <code>[Shape](#Shape)</code>
162+
<a name="Shape+setHeight"></a>
163+
164+
### shape.setHeight([height]) ⇒ <code>[Shape](#Shape)</code>
165+
Set new shape height.
166+
167+
**Kind**: instance method of <code>[Shape](#Shape)</code>
168+
169+
| Param | Type | Default | Description |
170+
| --- | --- | --- | --- |
171+
| [height] | <code>Number</code> &#124; <code>String</code> | <code>5</code> | Shape height |
172+
173+
**Example**
174+
```js
175+
shape.setHeight(15); // shape height is equal to 15 cells in the terminal
176+
shape.setHeight('20%'); // shape height is equal to 20% of total viewport height
177+
```
178+
<a name="Shape+getX"></a>
179+
180+
### shape.getX() ⇒ <code>Number</code>
181+
Get X coordinate.
182+
183+
**Kind**: instance method of <code>[Shape](#Shape)</code>
184+
<a name="Shape+setX"></a>
185+
186+
### shape.setX([x]) ⇒ <code>[Shape](#Shape)</code>
187+
Set X coordinate.
188+
189+
**Kind**: instance method of <code>[Shape](#Shape)</code>
190+
191+
| Param | Type | Default |
192+
| --- | --- | --- |
193+
| [x] | <code>Number</code> &#124; <code>String</code> | <code>10</code> |
194+
195+
**Example**
196+
```js
197+
shape.setX(2); // move shape to third cell by X axis
198+
shape.setX('left'); // align shape to the left
199+
shape.setX('center'); // align shape in the center
200+
shape.setX('right'); // align shape to the right
201+
shape.setX('50%'); // move shape to 50% by X axis
202+
```
203+
<a name="Shape+getY"></a>
204+
205+
### shape.getY() ⇒ <code>Number</code>
206+
Get Y coordinate.
207+
208+
**Kind**: instance method of <code>[Shape](#Shape)</code>
209+
<a name="Shape+setY"></a>
210+
211+
### shape.setY([y]) ⇒ <code>[Shape](#Shape)</code>
212+
Set Y coordinate.
213+
214+
**Kind**: instance method of <code>[Shape](#Shape)</code>
215+
216+
| Param | Type | Default |
217+
| --- | --- | --- |
218+
| [y] | <code>Number</code> &#124; <code>String</code> | <code>10</code> |
219+
220+
**Example**
221+
```js
222+
shape.setY(2); // move shape to third cell by Y axis
223+
shape.setY('top'); // align shape to the top
224+
shape.setY('middle'); // align shape in the middle
225+
shape.setY('bottom'); // align shape to the bottom
226+
shape.setY('50%'); // move shape to 50% by Y axis
227+
```
228+
<a name="Shape+getBackground"></a>
229+
230+
### shape.getBackground() ⇒ <code>String</code> &#124; <code>Boolean</code>
231+
Get background color.
232+
233+
**Kind**: instance method of <code>[Shape](#Shape)</code>
234+
<a name="Shape+setBackground"></a>
235+
236+
### shape.setBackground([background]) ⇒ <code>[Shape](#Shape)</code>
237+
Set new background color.
238+
239+
**Kind**: instance method of <code>[Shape](#Shape)</code>
240+
241+
| Param | Type | Default | Description |
242+
| --- | --- | --- | --- |
243+
| [background] | <code>String</code> &#124; <code>Boolean</code> | <code>false</code> | Color name, rgb, hex or false if you want to disable background |
244+
245+
**Example**
246+
```js
247+
shape.setBackground('black');
248+
shape.setBackground('#AABBCC');
249+
shape.setBackground('rgb(0, 100, 200)');
250+
shape.setBackground(false);
251+
```
252+
<a name="Shape+getForeground"></a>
253+
254+
### shape.getForeground() ⇒ <code>String</code> &#124; <code>Boolean</code>
255+
Get foreground color.
256+
257+
**Kind**: instance method of <code>[Shape](#Shape)</code>
258+
<a name="Shape+setForeground"></a>
259+
260+
### shape.setForeground([foreground]) ⇒ <code>[Shape](#Shape)</code>
261+
Set new foreground color.
262+
263+
**Kind**: instance method of <code>[Shape](#Shape)</code>
264+
265+
| Param | Type | Default | Description |
266+
| --- | --- | --- | --- |
267+
| [foreground] | <code>String</code> &#124; <code>Boolean</code> | <code>false</code> | Color name, rgb, hex or false if you want to disable foreground |
268+
269+
**Example**
270+
```js
271+
shape.setForeground('black');
272+
shape.setForeground('#AABBCC');
273+
shape.setForeground('rgb(0, 100, 200)');
274+
shape.setForeground(false);
275+
```
276+
<a name="Shape+render"></a>
277+
278+
### *shape.render()*
279+
Base render method that must be implemented in childes.
280+
281+
**Kind**: instance abstract method of <code>[Shape](#Shape)</code>
282+
**Throws**:
283+
284+
- <code>Error</code> Throws error if method is not overridden
285+
286+
<a name="Shape+toObject"></a>
287+
288+
### shape.toObject() ⇒ <code>Object</code>
289+
Returns Object representation of the shape.
290+
This representation consists of all options fields that you can pass in the constructor.
291+
292+
**Kind**: instance method of <code>[Shape](#Shape)</code>
293+
<a name="Shape+toJSON"></a>
294+
295+
### shape.toJSON() ⇒ <code>JSON</code>
296+
Returns JSON representation of the shape.
297+
298+
**Kind**: instance method of <code>[Shape](#Shape)</code>
299+
<a name="Shape.create"></a>
300+
301+
### Shape.create(args) ⇒ <code>[Shape](#Shape)</code>
302+
Wrapper around `new Shape()`.
303+
304+
**Kind**: static method of <code>[Shape](#Shape)</code>
305+
306+
| Param | Type |
307+
| --- | --- |
308+
| args | <code>\*</code> |
309+
310+
<a name="Shape.fromObject"></a>
311+
312+
### Shape.fromObject(obj, [cursor]) ⇒ <code>[Shape](#Shape)</code>
313+
Creates new Shape instance from Object representation.
314+
You can ignore cursor param and create only Shape representation.
315+
Though, you can add cursor in the runtime via [setCursor](setCursor) method.
316+
317+
**Kind**: static method of <code>[Shape](#Shape)</code>
318+
319+
| Param | Type | Description |
320+
| --- | --- | --- |
321+
| obj | <code>Object</code> | Object that you got from [toObject](toObject) method |
322+
| [cursor] | <code>Cursor</code> | Cursor instance |
323+
324+
<a name="Shape.fromJSON"></a>
325+
326+
### Shape.fromJSON(json, [cursor]) ⇒ <code>[Shape](#Shape)</code>
327+
Creates new Shape instance from JSON representation.
328+
You can ignore cursor param and create only Shape representation.
329+
Though, you can add cursor in the runtime via [setCursor](setCursor) method.
330+
331+
**Kind**: static method of <code>[Shape](#Shape)</code>
332+
333+
| Param | Type | Description |
334+
| --- | --- | --- |
335+
| json | <code>String</code> | JSON string that you got from [Shape.toJSON](Shape.toJSON) |
336+
| [cursor] | <code>Cursor</code> | Cursor instance |
337+

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
"clean": "rm -rf ./lib",
1818
"compile": "npm run clean; babel src --out-dir lib",
1919
"coveralls": "cat ./coverage/lcov.info | coveralls",
20+
"docs": "npm run compile; jsdoc2md \"lib/**/*.js\" > API.md",
2021
"prepublish": "npm run compile",
2122
"semantic-release": "semantic-release pre && npm publish && semantic-release post",
2223
"test": "babel-node ./node_modules/.bin/isparta cover _mocha"
@@ -30,6 +31,7 @@
3031
"coveralls": "2.11.9",
3132
"cz-conventional-changelog": "1.1.5",
3233
"isparta": "4.0.0",
34+
"jsdoc-to-markdown": "1.3.3",
3335
"kittik-cursor": "4.1.0",
3436
"mocha": "2.4.5",
3537
"semantic-release": "4.3.5",

0 commit comments

Comments
 (0)