Ink-use-input-hints NPM

ink-use-input-hints

A facade for ink useInput hook using a builder API and adding helpers for generating the hint bar.

Installation

npm install ink-use-input-hints

Quick start example

App.js

const { InputHints } = require('ink-use-input-hints');
const App = () => (
    <InputHints>
        <SubComponent/>
    </InputHints>
)

SubComponent.js

const { useInputWithHints } = require('ink-use-input-hints');
const SubComponent = () => {     
    useInputWithHints((handler, { KEYS }) => handler
            .add([KEYS.leftArrow, 'h'], () => {
                // handle movement left
            }, {description: 'move left'})
            .add([KEYS.rightArrow, 'l'], () => {
                // handle movement right
            }, {description: 'move right'})
            .add(['^'], () => {
                // handle going to start
            }, {description: 'go to start'})
            .add(['$'], () => {
                // handle going to end
            }, {description: 'go to end'})
            .add([KEYS.return], () => {
                // submit, wont be shown in hint bar
            }) 
    );
    return (<></>)
}

Bottom of App should show the bar with the keyboard hints:

Screenshot

Background

I enjoy Ink very much and find myself reusing the hint bar again and again, so I've decided to extract it out. I found the builder API more intuitive for reuse (for example, having the same keys do similar things across different screens).

API

Module exports the following members:

config

A map with parameters configuring the library behaviour; the keys of interest are:

AUTO_UPDATE_HINTS - default: true When set to true, list of hints (hints array of InputHintsContext) will be automatically updated each time useInputWithHints is called.
KEY_FORMATTER_FN - a function which accepts an object {index, key} and returns a string. This is used to format the key description part of the hint.
For example, in the above screenshot, hint for handling [KEYS.leftArrow, 'h'] is displayed as "h, <LEFT_ARROW> -- move left". Let's say we change this:
```
    config.set('KEY_FORMATTER_FN', ({index, key}) => `${key} (${index+1})`)
```
Now, the hint for handling [KEYS.leftArrow, 'h'] would be displayed as "h (0), leftArrow (1) -- move left".
HINT_FORMATTER_FN - a function which accepts an object {index, formattedKeyDescriptions, description} and returns a string. This governs how the individual hint text is generated from the list of keys and it's description. index is the index of the hint. formattedKeyDescriptions is an array of strings representing key descriptions (as returned by KEY_FORMATTER_FN). description is a description text provided in useInputWithHints handler. The default value (generating the output in the above example) looks like this:
```
config.set('HINT_FORMATTER_FN', ({
  index,
  formattedKeyDescriptions,
  description
}) => {
  const sortedByLength = sortBy(formattedKeyDescriptions, desc => desc.length);
  const keyList = sortedByLength.join(', ');
  return `${keyList} -- ${description}`;
});
```

InputHintsContext

A react context for sharing data (hints) between the useInputWithHints hook and the components displaying them (such as HintBar). If you want to manually manage the hints, you can use this.

const { InputHintsContext } = require('ink-use-input-hints');
// ...
const inputHintsContext = useContext(InputHintsContext);
inputHintsContext.setHints(['my','custom','hints']);
inputHintsContext.hints // array containing ['my','custom','hints']

InputHintsContextProvider

Provider for InputHintsContext. Provides hints and setHints. Already contained in InputHints.

useInputWithHints

Hook for handling user input and adding movement hints. Similar to useInput.

const hints = useInputWithHints(definerFunction);

To define how the user input is handled, you pass in definerFunction, which will be provided with two objects - handler and options, i.e. definerFunction(handlersBuilder, options);

handlersBuilder has the following methods:

add which accepts three arguments: handlersBuilder.add(keyList, handler, additionalOptions)
- keyList - array of inputs for which the handler should be triggered. Each element is either a single character, or a string representing a "special" key ('return', 'ctrl', 'leftArrow'.. ) The list matches the possible key names of the second argument to the original useInput. All of the values are accessible via the KEYS object.
- handler - this is called when user presses one of the keys in keyList, like the inputHandler for useInput.
- additionalOptions - object containing a single key, description - used for generating hints. If it's not provided, a hint for this keyList won't be generated
describe which accepts a single string argument - handlersBuilder.describe(text)
- this will just add text to the list of hints visible in the hint bar
The options argument to definerFunction has a single key, KEYS, which is an object listing all the recognizable special keys.

Finally, useInputWithHints returns an array listing generated hints.

const hints = useInputWithHints((handler, { KEYS }) => handler
          .add([KEYS.return, 'C'], () => {
              console.log('Submit!');
              submitInfo();
          }, {description: 'Submits the form'})
);
// hints === ['C, <RETURN> -- Submits the form']
// when user presses <RETURN> or C, the method submitInfo is called

KEYS

Contains all of the recognizable special keys:

const KEYS = {
  upArrow: 'upArrow',
  downArrow: 'downArrow',
  leftArrow: 'leftArrow',
  rightArrow: 'rightArrow',
  pageDown: 'pageDown',
  pageUp: 'pageUp',
  return: 'return',
  escape: 'escape',
  ctrl: 'ctrl',
  shift: 'shift',
  tab: 'tab',
  backspace: 'backspace',
  delete: 'delete',
  meta: 'meta'
}

InputHints

A component which wraps all the children in InputHintsContextProvider and draws the <HintBar/> below them. Can be passed an object ({wrapperProps: {..}, itemWrapperProps: {..}, textProps: {..}}) specifying how the hintBar is drawn.

<InputHints hintBarProps={{
    textProps: {backgroundColor: 'black', color: 'white'}
}}>
    ...
</InputHints>

HintBar

Default component for drawing default bar with hints. Accepts the following attributes:

hints - array of hints. If not provided, it will use InputHintsContextProvider
wrapperProps - object containing attributes for styling the Ink Box containing the hint bar
itemWrapperProps - object containing attributes for styling the Box wrapping the individual hint
textProps - object containing attributes for styling the text display of an individual hint. Ink's Text component is used for this, so attributes are the same.