You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: CHANGELOG.md
+45-12
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,36 @@
1
+
# v5.0.0
2
+
3
+
This version brings with it several new major features to react-console-emulator.
4
+
5
+
### Breaking changes
6
+
7
+
The recommended method for terminal input text styling has been moved. Terminal input text should now be styled using the `inputTextStyle` and `inputTextClassName` props. **Note:** If using the newly-introduced styling persistence options for command echoes, leaving text styling in `inputStyle` or `inputClassName` may cause unexpected styling bugs.
8
+
9
+
The `styleEchoBack` prop no longer accepts boolean input. Instead, one should either omit it (For default behaviour) or define one of the string types detailed in the [options](docs/CONFIG.md#options).
10
+
11
+
### Main changes
12
+
13
+
Async command executor support is here! You can now use async functions as command handlers and their outputs will function identically to synchronous functions.
14
+
15
+
Added the ability to hide the prompt area entirely when the terminal is disabled either manually through the `disabled` prop or on process if `disableOnProcess` is enabled. ([#639](https://github.com/linuswillner/react-console-emulator/issues/639))
16
+
17
+
Added the ability to set the terminal to read-only mode with the `readOnly` prop, which disables input entirely and hides the prompt area. ([#639](https://github.com/linuswillner/react-console-emulator/issues/639))
18
+
19
+
Added the ability to lock terminal output to updating the last line only. This could be useful for, among other things, creating progress bars. ([#638](https://github.com/linuswillner/react-console-emulator/issues/638))
20
+
21
+
### Other changes
22
+
23
+
Fixed a bug where newline parsing did not recognise newline literals properly. ([#632](https://github.com/linuswillner/react-console-emulator/issues/632))
24
+
25
+
Full run-down of prop changes:
26
+
```diff
27
+
+ inputTextStyle
28
+
+ inputTextClassName
29
+
+ hidePromptWhenDisabled
30
+
+ readOnly
31
+
+ locked
32
+
```
33
+
1
34
# v4.0.1
2
35
3
36
Correct eslint-config-standard-react getting installed as a production dependency as opposed to a development one.
@@ -16,14 +49,14 @@ Renamed `noAutomaticStdout` prop to `noEchoBack` for added clarity.
16
49
17
50
### Main changes
18
51
19
-
Terminal message styling is here! You can now re-style the messages output by the terminal (Including echoes, optionally with the `styleEchoBack` prop) using the `messageStyle` and `messageClassName` props ([#518](https://github.com/linuswillner/react-console-emulator/issues/518)).
52
+
Terminal message styling is here! You can now re-style the messages output by the terminal (Including echoes, optionally with the `styleEchoBack` prop) using the `messageStyle` and `messageClassName` props. ([#518](https://github.com/linuswillner/react-console-emulator/issues/518))
20
53
21
-
JSX prompt labels! Prompt labels now support elements instead of just plain old strings ([#210](https://github.com/linuswillner/react-console-emulator/issues/210)).
54
+
JSX prompt labels! Prompt labels now support elements instead of just plain old strings. ([#210](https://github.com/linuswillner/react-console-emulator/issues/210))
22
55
23
-
Newline parsing is now possible! The terminal can now parse newline characters in terminal messages - anything with a \n character in it will be rendered as a separate line in the response message. This does of course not apply to command back-echoes. This behaviour can also be disabled, if desired, using the `noNewlineParsing` prop ([#519](https://github.com/linuswillner/react-console-emulator/issues/519)).
56
+
Newline parsing is now possible! The terminal can now parse newline characters in terminal messages - anything with a \n character in it will be rendered as a separate line in the response message. This does of course not apply to command back-echoes. This behaviour can also be disabled, if desired, using the `noNewlineParsing` prop. ([#519](https://github.com/linuswillner/react-console-emulator/issues/519))
24
57
25
58
26
-
Case-insensitive command matching! You can now supply the `ignoreCommandCase` prop to allow matching commands even when their casing is not correct. Do note that for security reasons, enabling case-insensitive command matching restricts command names to letters, numbers and dashes/underscores ([#415](https://github.com/linuswillner/react-console-emulator/issues/415)).
59
+
Case-insensitive command matching! You can now supply the `ignoreCommandCase` prop to allow matching commands even when their casing is not correct. Do note that for security reasons, enabling case-insensitive command matching restricts command names to letters, numbers and dashes/underscores. ([#415](https://github.com/linuswillner/react-console-emulator/issues/415))
27
60
28
61
### Other changes
29
62
@@ -47,19 +80,19 @@ A full run-down of the prop changes is as follows:
47
80
48
81
# v3.0.4
49
82
50
-
Fixed a bug preventing users from selecting text in the terminal output ([#414](https://github.com/linuswillner/react-console-emulator/issues/414)).
83
+
Fixed a bug preventing users from selecting text in the terminal output. ([#414](https://github.com/linuswillner/react-console-emulator/issues/414))
51
84
52
85
# v3.0.3
53
86
54
-
Removed redundant `stringify-object` dependency to properly enable command re-validation based on raw objects alone. This was supposed to have been fixed in 3.0.2, but due to a mishap the old validation was left dangling. This has now been fixed ([#411](https://github.com/linuswillner/react-console-emulator/issues/411)).
87
+
Removed redundant `stringify-object` dependency to properly enable command re-validation based on raw objects alone. This was supposed to have been fixed in 3.0.2, but due to a mishap the old validation was left dangling. This has now been fixed. ([#411](https://github.com/linuswillner/react-console-emulator/issues/411))
55
88
56
89
# v3.0.2
57
90
58
-
Fixed command re-validation reliability issues relating to source-identical commands ([#35](https://github.com/linuswillner/react-console-emulator/issues/35)).
91
+
Fixed command re-validation reliability issues relating to source-identical commands. ([#35](https://github.com/linuswillner/react-console-emulator/issues/35))
59
92
60
93
# v3.0.1
61
94
62
-
Fixed input outline showing on Safari ([#258](https://github.com/linuswillner/react-console-emulator/pull/258)) ([Herve07h22](https://github.com/Herve07h22)).
95
+
Fixed input outline showing on Safari. ([Herve07h22](https://github.com/Herve07h22)) ([#258](https://github.com/linuswillner/react-console-emulator/pull/258))
63
96
64
97
# v3.0.0
65
98
@@ -119,19 +152,19 @@ Enabled module transpilation to widen the support amongst Node versions for dist
119
152
120
153
# v1.7.2
121
154
122
-
Re-added Babel into build flow in a different format to improve compatibility ([#39, comment](https://github.com/linuswillner/react-console-emulator/issues/39#issuecomment-440973765)).
155
+
Re-added Babel into build flow in a different format to improve compatibility. ([#39, comment](https://github.com/linuswillner/react-console-emulator/issues/39#issuecomment-440973765))
123
156
124
157
# v1.7.1
125
158
126
-
Removed Babel from the build flow in order to allow the inclusion of the helper files ([#39](https://github.com/linuswillner/react-console-emulator/issues/39)).
159
+
Removed Babel from the build flow in order to allow the inclusion of the helper files. ([#39](https://github.com/linuswillner/react-console-emulator/issues/39))
127
160
128
161
# v1.7.0
129
162
130
163
Internal refactoring for better maintainability.
131
164
132
-
Added default-enabled automatic scrolling to the bottom of the terminal when a command is run ([#36](https://github.com/linuswillner/react-console-emulator/issues/36)).
165
+
Added default-enabled automatic scrolling to the bottom of the terminal when a command is run. ([#36](https://github.com/linuswillner/react-console-emulator/issues/36))
133
166
134
-
Added command callback support to run a function each time a command is executed ([#36](https://github.com/linuswillner/react-console-emulator/issues/36)).
167
+
Added command callback support to run a function each time a command is executed. ([#36](https://github.com/linuswillner/react-console-emulator/issues/36))
Copy file name to clipboardexpand all lines: docs/API.md
+15-2
Original file line number
Diff line number
Diff line change
@@ -17,20 +17,33 @@ const commands = {
17
17
constlowerCaseArg1=arg1.toLowerCase()
18
18
19
19
// What you return in this function will be output to the terminal
20
+
// If you want to render non-string items, stringify them before outputting them here
20
21
return`test ${lowerCaseArg1}`
21
22
},
22
23
explicitExec:true, // If you need to execute your function again after the output has been emitted, enable
23
24
}
24
25
}
25
26
```
26
27
28
+
### Sync vs async command functions
29
+
30
+
Command functions (The `fn` property) can be sync or async. Asynchronous functions are awaited and their return values are displayed as those of a regular function would.
31
+
32
+
This is particularly useful if you have to make relatively low-latency operations like network requests and display their outputs. However, if your tasks are predicted to take longer than is feasible to wait for with a promise, see the [Async output](#async-output) section below.
33
+
34
+
### Updating terminal output
35
+
36
+
Akin to native terminals, the terminal output can at will be locked (Using the `locked` prop) to redirect all output to only replace the latest line, as opposed to pushing new lines. This can be utilised along with [Async output](#async-output) to, for example, create a continually incrementing progress bar.
37
+
38
+
**Note:** It might be worth setting the `locked` prop conditionally only when a command is run, if you do not want your welcome message to disappear, or get stripped down to only the last one if you're using a multi-message welcome, considering welcome messages behave exactly like ordinary user-triggered outputs.
39
+
27
40
### Async output
28
41
29
-
If you terminal deals with HTTP requests or cross-component functionality, you may need to wait for a result before pushing to the output without relying on the function return time.
42
+
If your terminal commands need to perform tasks with significant delays (Wait for events, etc.) that cause promise resolution times to be prohibitively long, you may need to return a temporary value and then wait for a result before pushing to the output.
30
43
31
44
**Note:** Doing output this way is a workaround, and ideally your output should be returned by the command function. This method will expose functions to you that you do not normally have access to due to React component encapsulation. Proceed with caution.
32
45
33
-
To do this, you can use the [React refs API](https://reactjs.org/docs/refs-and-the-dom.html). Below is an example component that uses async pushing.
46
+
To do this, you can use the [React refs API](https://reactjs.org/docs/refs-and-the-dom.html). Below is an example component that uses asynchronous output in this manner.
The different labels used by the terminal can be easily changed via the following props.
34
-
35
-
| Prop | Description | Type | Default |
36
-
| ---- | ----------- | ---- | ------- |
37
-
| welcomeMessage | The terminal welcome message. Set to `false` to disable, `true` to show the default, or supply a string (Or an array of them) to set a custom one. | Boolean/String/Array<String\>|`false`|
38
-
| promptLabel | The prefix to use for the input field. Can be either string or element. | Node |`$`|
39
-
| errorText | The text to display when a command does not exist. Use the `[command]` placeholder for input substitution. | String |`Command '[command]' not found!`|
40
-
41
30
### Options
42
31
43
-
The terminal has several options you can use to change the behaviour of it.
32
+
The terminal has several options you can use to change the behaviour of it. All props in this section are optional.
44
33
45
34
| Prop | Description | Type | Default |
46
35
| ---- | ----------- | ---- | ------- |
47
36
| autoFocus | Focus the terminal on page load. | Boolean |`false`|
48
37
| dangerMode | Enable parsing of HTML in terminal messages. | Boolean |`false`|
49
38
| disabled | Whether to enable terminal input or not. | Boolean |`false`|
50
39
| disableOnProcess | Disable input to the terminal during command execution. | Boolean |`false`|
51
-
| styleEchoBack | Style command echoes (Terminal outputs of any commands entered) as regular terminal messages. | Boolean |`false`|
40
+
| errorText | The text to display when a command does not exist. Use the `[command]` placeholder for input substitution. | String |`'Command \'[command]\' not found!'`|
41
+
| hidePromptWhenDisabled | Hide entire prompt when input is manually disabled (Via the `disabled` prop) or when `disableOnProcess` is enabled and the terminal is processing. | Boolean |`false`|
42
+
| ignoreCommandCase | Disable case-sensitive matching of command inputs. **Note:** Enabling this feature results in a restriction of command names to alphanumeric characters, dashes and underscores, for security reasons. | Boolean |`false`|
43
+
| locked | Lock output to the current line. When this prop is set to `true`, all output to the terminal will only replace the latest line. This could be useful if you want to make something akin to a progress bar and update the latest line. | Boolean |`false`|
44
+
| noAutoScroll | Disable automatic scrolling to the bottom of the terminal when a command is executed (*nix-like). | Boolean |`false`|
52
45
| noDefaults | Do not register the default commands (`help` and `clear`). Useful if you want to override the functionality of either. | Boolean |`false`|
53
46
| noEchoBack | Disable command echoes (Terminal outputs of any commands entered). | Boolean |`false`|
54
47
| noHistory | Disable the storing and scrolling of history of the commands entered in the terminal. | Boolean |`false`|
55
-
| noAutoScroll | Disable automatic scrolling to the bottom of the terminal when a command is executed (*nix-like). | Boolean |`false`|
56
48
| noNewlineParsing | Disable the parsing line breaks (\n) in command outputs as separate message, leave them unchanged. | Boolean |`false`|
57
-
| ignoreCommandCase | Disable case-sensitive matching of command inputs. **Note:** Enabling this feature results in a restriction of command names to alphanumeric characters, dashes and underscores, for security reasons. | Boolean |`false`|
49
+
| promptLabel | The prefix to use for the input field. Can be either string or element. | Node |`$`|
50
+
| readOnly | Hides the entire prompt, thus setting the terminal to read-only mode. | Boolean |`false`|
51
+
| styleEchoBack | Inherit style for command echoes (Terminal outputs of any commands entered) from prompt (Fully or partially, i.e. label or text only), or style them as regular messages. Omitting this prop enables default behaviour. | String<'labelOnly'/'textOnly'/'fullInherit'/'messageInherit'\>|`undefined`|
52
+
| welcomeMessage | The terminal welcome message. Set to `false` to disable, `true` to show the default, or supply a string (Or an array of them) to set a custom one. | Boolean/String/Array<String\>|`false`|
58
53
59
54
### Re-styling
60
55
61
56
To re-style the terminal, you have two options: [Inline styles](https://reactjs.org/docs/dom-elements.html#style) or supplying a class name. The former is recommended due to it automatically overriding the previous property without having to faff about with `!important` and similar hacks.
62
57
63
58
The default styles for the terminal can be found in [src/defs/styles/Terminal.js](../src/defs/styles/Terminal.js). The definitions contained within can be adjusted by submitting style overrides or class names to the following props.
| inputAreaStyle / inputAreaClassName | Input area element (Container for prompt label and input field). |
70
67
| promptLabelStyle / promptLabelClassName | Prompt label (The prefix for the input). |
71
-
| inputStyle / inputClassName | Text input field. |
68
+
| inputStyle / inputClassName | Input field. **Note:** Applying styles for the text here may cause unexpected results, see below. |
69
+
| inputTextStyle / inputTextClassName | Input field text. |
72
70
| messageStyle / messageClassName | Terminal messages (Incl. command echoes if enabled via the `styleEchoBack` prop). |
73
71
72
+
**Note about input text styling:**
73
+
74
+
As of v5.0.0, input text styling has been moved to `inputTextStyle` and `inputTextClassName`. The reason for this is the introduction of prompt styling persistence for echoes in the same version. Despite the input text being part of the input element strictly speaking, **do not apply text styles in `inputStyle` or `inputClassName`, or you may see unexpected styling errors.**
75
+
74
76
Examples on how to override the terminal styles can be found in [src/App.jsx](../src/App.jsx).
0 commit comments