@sarthak_krishak/inkforge 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Readme.md +206 -93
- package/package.json +1 -1
package/Readme.md
CHANGED
|
@@ -1,154 +1,267 @@
|
|
|
1
|
-
#
|
|
1
|
+
# InkForge
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
<div align="center">
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@sarthak_krishak/inkforge)
|
|
6
|
+
[](https://www.npmjs.com/package/@sarthak_krishak/inkforge)
|
|
7
|
+
[](./LICENSE)
|
|
8
|
+
[](https://nodejs.org)
|
|
9
|
+
[](https://react.dev)
|
|
10
|
+
[](https://github.com/vadimdemedes/ink)
|
|
11
|
+
|
|
12
|
+
**Beautiful terminal UI components for React/Ink — set up in 2 commands, owned forever.**
|
|
13
|
+
|
|
14
|
+
*shadcn/ui for your terminal. Built for the AI coding agent era.*
|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## What is InkForge?
|
|
21
|
+
|
|
22
|
+
InkForge gives you polished, production-ready terminal components — spinners, progress bars, and more — that you **actually own**. Instead of a locked npm dependency you can't touch, InkForge copies the source code directly into your project. Read it. Edit it. Make it yours.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install @sarthak_krishak/inkforge react ink vite-node vite @vitejs/plugin-react
|
|
26
|
+
npx inkforge init
|
|
27
|
+
npm start
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
That's the entire setup. Three commands. You're running.
|
|
8
31
|
|
|
9
32
|
---
|
|
10
33
|
|
|
11
|
-
##
|
|
34
|
+
## Quick Start
|
|
35
|
+
|
|
36
|
+
### Step 1 — Create a new folder and open a terminal inside it
|
|
12
37
|
|
|
13
|
-
|
|
38
|
+
```bash
|
|
39
|
+
mkdir my-cli-app
|
|
40
|
+
cd my-cli-app
|
|
41
|
+
```
|
|
14
42
|
|
|
15
|
-
|
|
43
|
+
### Step 2 — Install InkForge and its dependencies
|
|
16
44
|
|
|
17
|
-
|
|
45
|
+
```bash
|
|
18
46
|
npm install @sarthak_krishak/inkforge react ink vite-node vite @vitejs/plugin-react
|
|
19
|
-
|
|
47
|
+
```
|
|
20
48
|
|
|
21
|
-
###
|
|
49
|
+
### Step 3 — Run init
|
|
22
50
|
|
|
23
|
-
|
|
51
|
+
```bash
|
|
24
52
|
npx inkforge init
|
|
25
|
-
|
|
53
|
+
```
|
|
26
54
|
|
|
27
|
-
This automatically creates everything
|
|
55
|
+
This one command automatically creates everything:
|
|
28
56
|
|
|
29
|
-
|
|
|
57
|
+
| Created | What it does |
|
|
30
58
|
|---|---|
|
|
31
|
-
| `package.json` |
|
|
32
|
-
| `vite.config.js` | Vite
|
|
33
|
-
| `app.jsx` | A working starter app
|
|
34
|
-
| `src/components/inkforge/Spinner/` | Spinner source — yours to edit |
|
|
35
|
-
| `src/components/inkforge/ProgressBar/` | ProgressBar source — yours to edit |
|
|
36
|
-
| `src/components/inkforge/core/colors.js` | Theme color
|
|
59
|
+
| `package.json` | Configured with `type: module` and a `start` script |
|
|
60
|
+
| `vite.config.js` | Vite + React plugin config |
|
|
61
|
+
| `app.jsx` | A working starter app with live examples |
|
|
62
|
+
| `src/components/inkforge/Spinner/` | Spinner source — yours to own and edit |
|
|
63
|
+
| `src/components/inkforge/ProgressBar/` | ProgressBar source — yours to own and edit |
|
|
64
|
+
| `src/components/inkforge/core/colors.js` | Theme color system |
|
|
37
65
|
|
|
38
|
-
###
|
|
66
|
+
### Step 4 — Start your app
|
|
39
67
|
|
|
40
|
-
|
|
68
|
+
```bash
|
|
41
69
|
npm start
|
|
42
|
-
|
|
70
|
+
```
|
|
43
71
|
|
|
44
|
-
You'll see animated spinners and a filling progress bar immediately.
|
|
72
|
+
You'll see animated spinners and a filling progress bar in your terminal immediately.
|
|
45
73
|
|
|
46
74
|
---
|
|
47
75
|
|
|
48
|
-
##
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
my-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
76
|
+
## Project structure after init
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
my-cli-app/
|
|
80
|
+
├── src/
|
|
81
|
+
│ └── components/
|
|
82
|
+
│ └── inkforge/
|
|
83
|
+
│ ├── Spinner/
|
|
84
|
+
│ │ └── index.jsx ← edit freely
|
|
85
|
+
│ ├── ProgressBar/
|
|
86
|
+
│ │ └── index.jsx ← edit freely
|
|
87
|
+
│ └── core/
|
|
88
|
+
│ └── colors.js ← theme colors
|
|
89
|
+
├── app.jsx ← your app starts here
|
|
90
|
+
├── vite.config.js
|
|
91
|
+
└── package.json
|
|
92
|
+
```
|
|
65
93
|
|
|
66
94
|
---
|
|
67
95
|
|
|
68
|
-
## Using
|
|
96
|
+
## Using components in your app
|
|
69
97
|
|
|
70
|
-
Open `app.jsx` and build from there:
|
|
98
|
+
Open `app.jsx` and build from there. The import paths are set up automatically:
|
|
71
99
|
|
|
72
|
-
|
|
73
|
-
import React from 'react';
|
|
100
|
+
```jsx
|
|
101
|
+
import React, { useState, useEffect } from 'react';
|
|
74
102
|
import { render, Box, Text } from 'ink';
|
|
75
103
|
import { Spinner } from './src/components/inkforge/Spinner/index.jsx';
|
|
76
104
|
import { ProgressBar } from './src/components/inkforge/ProgressBar/index.jsx';
|
|
77
105
|
|
|
78
106
|
function App() {
|
|
107
|
+
const [progress, setProgress] = useState(0);
|
|
108
|
+
const [done, setDone] = useState(false);
|
|
109
|
+
|
|
110
|
+
useEffect(() => {
|
|
111
|
+
const t = setInterval(() => {
|
|
112
|
+
setProgress(p => {
|
|
113
|
+
if (p >= 100) { clearInterval(t); setDone(true); return 100; }
|
|
114
|
+
return p + 5;
|
|
115
|
+
});
|
|
116
|
+
}, 150);
|
|
117
|
+
return () => clearInterval(t);
|
|
118
|
+
}, []);
|
|
119
|
+
|
|
79
120
|
return (
|
|
80
121
|
<Box flexDirection="column" padding={1} gap={1}>
|
|
81
122
|
<Text bold color="cyan">My CLI App</Text>
|
|
82
|
-
<Spinner
|
|
83
|
-
<ProgressBar value={
|
|
123
|
+
<Spinner label="Building..." done={done} doneText="✓ Build complete!" />
|
|
124
|
+
<ProgressBar value={progress} label="Progress" />
|
|
84
125
|
</Box>
|
|
85
126
|
);
|
|
86
127
|
}
|
|
87
128
|
|
|
88
129
|
render(<App />);
|
|
89
|
-
|
|
130
|
+
```
|
|
90
131
|
|
|
91
132
|
---
|
|
92
133
|
|
|
93
|
-
##
|
|
134
|
+
## Components
|
|
94
135
|
|
|
95
|
-
|
|
96
|
-
<Spinner variant="dots" label="Fetching..." />
|
|
97
|
-
<Spinner variant="bounce" label="Processing..." theme="cyberpunk" />
|
|
98
|
-
<Spinner variant="arc" label="Compiling..." />
|
|
99
|
-
<Spinner variant="line" label="Connecting..." />
|
|
100
|
-
<Spinner variant="simple" label="Waiting..." />
|
|
136
|
+
### Spinner
|
|
101
137
|
|
|
102
|
-
|
|
103
|
-
<Spinner label="Deploying..." done={isDone} doneText="✓ Deployed!" />
|
|
104
|
-
\`\`\`
|
|
138
|
+
Animated loading indicator with 5 variants and a done state.
|
|
105
139
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
140
|
+
```jsx
|
|
141
|
+
// Variants
|
|
142
|
+
<Spinner variant="dots" label="Fetching data..." />
|
|
143
|
+
<Spinner variant="bounce" label="Processing request..." theme="cyberpunk" />
|
|
144
|
+
<Spinner variant="arc" label="Compiling..." />
|
|
145
|
+
<Spinner variant="line" label="Connecting..." />
|
|
146
|
+
<Spinner variant="simple" label="Waiting..." />
|
|
147
|
+
|
|
148
|
+
// Done state — switches to a completion message automatically
|
|
149
|
+
<Spinner
|
|
150
|
+
label="Deploying to production..."
|
|
151
|
+
done={isDone}
|
|
152
|
+
doneText="✓ Deployed successfully!"
|
|
153
|
+
/>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
#### Spinner Props
|
|
157
|
+
|
|
158
|
+
| Prop | Type | Default | Description |
|
|
159
|
+
|---|---|---|---|
|
|
160
|
+
| `variant` | `string` | `'dots'` | Animation style: `dots` `line` `bounce` `arc` `simple` |
|
|
161
|
+
| `label` | `string` | `'Loading...'` | Text displayed next to the spinner |
|
|
162
|
+
| `color` | `string` | theme primary | Override spinner color (any hex value) |
|
|
163
|
+
| `theme` | `string` | `'default'` | Color theme: `'default'` or `'cyberpunk'` |
|
|
164
|
+
| `interval` | `number` | `120` | Animation frame speed in milliseconds |
|
|
165
|
+
| `done` | `boolean` | `false` | When `true`, switches to the done state |
|
|
166
|
+
| `doneText` | `string` | `'✓ Done'` | Message shown when `done` is `true` |
|
|
114
167
|
|
|
115
168
|
---
|
|
116
169
|
|
|
117
|
-
|
|
170
|
+
### ProgressBar
|
|
171
|
+
|
|
172
|
+
Fillable progress bar with 3 visual styles.
|
|
173
|
+
|
|
174
|
+
```jsx
|
|
175
|
+
// Basic usage
|
|
176
|
+
<ProgressBar value={75} label="Build" />
|
|
177
|
+
|
|
178
|
+
// Show raw value instead of percentage
|
|
179
|
+
<ProgressBar value={45} total={200} label="Files processed" showValue />
|
|
180
|
+
|
|
181
|
+
// Visual variants
|
|
182
|
+
<ProgressBar value={progress} variant="default" label="Download " />
|
|
183
|
+
<ProgressBar value={progress} variant="thin" label="Upload " />
|
|
184
|
+
<ProgressBar value={progress} variant="block" label="Memory " />
|
|
118
185
|
|
|
119
|
-
|
|
120
|
-
<ProgressBar value={
|
|
121
|
-
<ProgressBar value={45} total={200} label="Files" showValue />
|
|
122
|
-
<ProgressBar value={progress} variant="thin" label="Upload" />
|
|
123
|
-
<ProgressBar value={progress} variant="block" label="Memory" color="#E5C07B" />
|
|
124
|
-
<ProgressBar value={progress} theme="cyberpunk" label="Hack" />
|
|
125
|
-
\`\`\`
|
|
186
|
+
// Custom color
|
|
187
|
+
<ProgressBar value={progress} color="#E5C07B" label="CPU usage" />
|
|
126
188
|
|
|
127
|
-
|
|
189
|
+
// Cyberpunk theme
|
|
190
|
+
<ProgressBar value={progress} theme="cyberpunk" label="Hack " />
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
#### ProgressBar Props
|
|
194
|
+
|
|
195
|
+
| Prop | Type | Default | Description |
|
|
196
|
+
|---|---|---|---|
|
|
197
|
+
| `value` | `number` | `0` | Current progress value |
|
|
198
|
+
| `total` | `number` | `100` | Maximum value |
|
|
199
|
+
| `width` | `number` | `30` | Bar width in terminal characters |
|
|
200
|
+
| `label` | `string` | `''` | Label shown before the bar |
|
|
201
|
+
| `showPercent` | `boolean` | `true` | Show percentage on the right |
|
|
202
|
+
| `showValue` | `boolean` | `false` | Show `value/total` instead of percentage |
|
|
203
|
+
| `color` | `string` | theme success | Fill color (any hex value) |
|
|
204
|
+
| `bgColor` | `string` | theme muted | Empty bar color (any hex value) |
|
|
205
|
+
| `theme` | `string` | `'default'` | Color theme: `'default'` or `'cyberpunk'` |
|
|
206
|
+
| `variant` | `string` | `'default'` | Bar style: `'default'` `'thin'` `'block'` |
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Themes
|
|
211
|
+
|
|
212
|
+
All components support two built-in themes via the `theme` prop:
|
|
213
|
+
|
|
214
|
+
| Theme | Colors | Best for |
|
|
128
215
|
|---|---|---|
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
216
|
+
| `default` | Blue accent, green fill, gray empty | Production tools, professional CLIs |
|
|
217
|
+
| `cyberpunk` | Neon cyan, bright green, dark muted | Dev tools, personal projects, AI agents |
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## CLI Commands
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
# Set up a new project from scratch (run once after install)
|
|
225
|
+
npx inkforge init
|
|
226
|
+
|
|
227
|
+
# Add a specific component to an existing project
|
|
228
|
+
npx inkforge add spinner
|
|
229
|
+
npx inkforge add progressbar
|
|
230
|
+
npx inkforge add spinner progressbar
|
|
231
|
+
|
|
232
|
+
# Interactive component selector (arrow keys + space to pick)
|
|
233
|
+
npx inkforge add
|
|
234
|
+
|
|
235
|
+
# List all available components
|
|
236
|
+
npx inkforge list
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Why own your components?
|
|
242
|
+
|
|
243
|
+
With a standard npm package, the code lives locked inside `node_modules`. You can't edit it without forking the whole repo.
|
|
244
|
+
|
|
245
|
+
With InkForge, after running `npx inkforge add spinner`, the file lives at `src/components/inkforge/Spinner/index.jsx` — inside **your** project. Open it, change the animation frames, add a new variant, tweak the colors. No fork needed. No PR required. It's your code now.
|
|
246
|
+
|
|
247
|
+
This is the same philosophy that made [shadcn/ui](https://ui.shadcn.com) popular for web development. InkForge brings it to the terminal.
|
|
138
248
|
|
|
139
249
|
---
|
|
140
250
|
|
|
141
|
-
##
|
|
251
|
+
## Roadmap
|
|
142
252
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
253
|
+
- [x] Spinner — 5 variants, done state, theme support
|
|
254
|
+
- [x] ProgressBar — 3 variants, custom colors, theme support
|
|
255
|
+
- [x] CLI installer — `init`, `add`, `list` commands
|
|
256
|
+
- [ ] DiffViewer — git-style diff display for AI coding agents
|
|
257
|
+
- [ ] StreamingOutput — token-by-token streaming display
|
|
258
|
+
- [ ] PromptInput — input with history and autocomplete
|
|
259
|
+
- [ ] Select / MultiSelect — keyboard-navigable menus
|
|
260
|
+
- [ ] Table — structured data display
|
|
261
|
+
- [ ] StatusBar — footer with agent state and metrics
|
|
149
262
|
|
|
150
263
|
---
|
|
151
264
|
|
|
152
265
|
## License
|
|
153
266
|
|
|
154
|
-
MIT
|
|
267
|
+
MIT © [Sarthak Krishak](https://github.com/SarthakKrishak)
|