Add focus management

examples/use-focus/index.js

@@ -0,0 +1,2 @@
+'use strict';
+require('import-jsx')('./use-focus');

examples/use-focus/use-focus.js

@@ -0,0 +1,27 @@
+/* eslint-disable react/prop-types */
+'use strict';
+const React = require('react');
+const {render, Box, Text, Color, useFocus} = require('../..');
+
+const Focus = () => (
+ <Box flexDirection="column" padding={1}>
+ <Box marginBottom={1}>
+ Press Tab to focus next element, Shift+Tab to focus previous element, Esc
+ to reset focus.
+ </Box>
+ <Item label="First" />
+ <Item label="Second" />
+ <Item label="Third" />
+ </Box>
+);
+
+const Item = ({label}) => {
+ const {isFocused} = useFocus();
+ return (
+ <Text>
+ {label} {isFocused && <Color green>(focused)</Color>}
+ </Text>
+ );
+};
+
+render(<Focus />);

readme.md

@@ -1108,6 +1108,128 @@ const Example = () => {
 };
 ```
 
+### useFocus(options?)
+
+Component that uses `useFocus` hook becomes "focusable" to Ink, so when user presses <kbd>Tab</kbd>, Ink will switch focus to this component.
+If there are multiple components that execute `useFocus` hook, focus will be given to them in the order that these components are rendered in.
+This hook returns an object with `isFocused` boolean property, which determines if this component is focused or not.
+
+#### options
+
+##### autoFocus
+
+Type: `boolean`<br>
+Default: `false`
+
+Auto focus this component, if there's no active (focused) component right now.
+
+##### isActive
+
+Type: `boolean`<br>
+Default: `true`
+
+Enable or disable this component's focus, while still maintaining its position in the list of focusable components.
+This is useful for inputs that are temporarily disabled.
+
+```js
+import {useFocus} from 'ink';
+
+const Example = () => {
+ const {isFocused} = useFocus();
+
+ return <Text>{isFocused ? 'I am focused' : 'I am not focused'}</Text>;
+};
+```
+
+See example in [examples/use-focus](examples/use-focus/use-focus.js).
+
+### useFocusManager
+
+This hook exposes methods to enable or disable focus management for all components or manually switch focus to next or previous components.
+
+#### enableFocus()
+
+Enable focus management for all components.
+
+**Note:** You don't need to call this method manually, unless you've disabled focus management. Focus management is enabled by default.
+
+```js
+import {useFocusManager} from 'ink';
+
+const Example = () => {
+ const {enableFocus} = useFocusManager();
+
+ useEffect(() => {
+ enableFocus();
+ }, []);
+
+ return …
+};
+```
+
+#### disableFocus()
+
+Disable focus management for all components.
+Currently active component (if there's one) will lose its focus.
+
+```js
+import {useFocusManager} from 'ink';
+
+const Example = () => {
+ const {disableFocus} = useFocusManager();
+
+ useEffect(() => {
+ disableFocus();
+ }, []);
+
+ return …
+};
+```
+
+#### focusNext()
+
+Switch focus to the next focusable component.
+If there's no active component right now, focus will be given to the first focusable component.
+If active component is the last in the list of focusable components, focus will be switched to the first component.
+
+**Note:** Ink calls this method when user presses <kbd>Tab</kbd>.
+
+```js
+import {useFocusManager} from 'ink';
+
+const Example = () => {
+ const {focusNext} = useFocusManager();
+
+ useEffect(() => {
+ focusNext();
+ }, []);
+
+ return …
+};
+```
+
+#### focusPrevious()
+
+Switch focus to the previous focusable component.
+If there's no active component right now, focus will be given to the first focusable component.
+If active component is the first in the list of focusable components, focus will be switched to the last component.
+
+**Note:** Ink calls this method when user presses <kbd>Shift</kbd>+<kbd>Tab</kbd>.
+
+```js
+import {useFocusManager} from 'ink';
+
+const Example = () => {
+ const {focusPrevious} = useFocusManager();
+
+ useEffect(() => {
+ focusPrevious();
+ }, []);
+
+ return …
+};
+```
+
 ## Useful Hooks
 
 - [ink-use-stdout-dimensions](https:/cameronhunter/ink-monorepo/tree/master/packages/ink-use-stdout-dimensions) - Subscribe to stdout dimensions.

src/components/App.tsx

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/prefer-nullish-coalescing */
 import React, {PureComponent} from 'react';
 import type {ReactNode} from 'react';
 import PropTypes from 'prop-types';
@@ -6,6 +7,11 @@ import AppContext from './AppContext';
 import StdinContext from './StdinContext';
 import StdoutContext from './StdoutContext';
 import StderrContext from './StderrContext';
+import FocusContext from './FocusContext';
+
+const TAB = '\t';
+const SHIFT_TAB = '\u001B[Z';
+const ESC = '\u001B';
 
 interface Props {
  children: ReactNode;
@@ -18,10 +24,21 @@ interface Props {
  onExit: (error?: Error) => void;
 }
 
+interface State {
+ isFocusEnabled: boolean;
+ activeFocusId?: string;
+ focusables: Focusable[];
+}
+
+interface Focusable {
+ id: string;
+ isActive: boolean;
+}
+
 // Root component for all Ink apps
 // It renders stdin and stdout contexts, so that children can access them if needed
 // It also handles Ctrl+C exiting and cursor visibility
-export default class App extends PureComponent<Props> {
+export default class App extends PureComponent<Props, State> {
  static displayName = 'InternalApp';
  static propTypes = {
  children: PropTypes.node.isRequired,
@@ -34,6 +51,12 @@ export default class App extends PureComponent<Props> {
  onExit: PropTypes.func.isRequired
  };
 
+ state = {
+ isFocusEnabled: true,
+ activeFocusId: undefined,
+ focusables: []
+ };
+
  // Count how many components enabled raw mode to avoid disabling
  // raw mode until all components don't need it anymore
  rawModeEnabledCount = 0;
@@ -69,7 +92,21 @@ export default class App extends PureComponent<Props> {
  write: this.props.writeToStderr
  }}
  >
- {this.props.children}
+ <FocusContext.Provider
+ value={{
+ activeId: this.state.activeFocusId,
+ add: this.addFocusable,
+ remove: this.removeFocusable,
+ activate: this.activateFocusable,
+ deactivate: this.deactivateFocusable,
+ enableFocus: this.enableFocus,
+ disableFocus: this.disableFocus,
+ focusNext: this.focusNext,
+ focusPrevious: this.focusPrevious
+ }}
+ >
+ {this.props.children}
+ </FocusContext.Provider>
  </StderrContext.Provider>
  </StdoutContext.Provider>
  </StdinContext.Provider>
@@ -137,6 +174,23 @@ export default class App extends PureComponent<Props> {
  if (input === '\x03' && this.props.exitOnCtrlC) {
  this.handleExit();
  }
+
+ // Reset focus when there's an active focused component on Esc
+ if (input === ESC && this.state.activeFocusId) {
+ this.setState({
+ activeFocusId: undefined
+ });
+ }
+
+ if (this.state.isFocusEnabled && this.state.focusables.length > 0) {
+ if (input === TAB) {
+ this.focusNext();
+ }
+
+ if (input === SHIFT_TAB) {
+ this.focusPrevious();
+ }
+ }
  };
 
  handleExit = (error?: Error): void => {
@@ -146,4 +200,139 @@ export default class App extends PureComponent<Props> {
 
  this.props.onExit(error);
  };
+
+ enableFocus = (): void => {
+ this.setState({
+ isFocusEnabled: true
+ });
+ };
+
+ disableFocus = (): void => {
+ this.setState({
+ isFocusEnabled: false
+ });
+ };
+
+ focusNext = (): void => {
+ this.setState(previousState => {
+ const firstFocusableId = previousState.focusables[0].id;
+ const nextFocusableId = this.findNextFocusable(previousState);
+
+ return {
+ activeFocusId: nextFocusableId || firstFocusableId
+ };
+ });
+ };
+
+ focusPrevious = (): void => {
+ this.setState(previousState => {
+ const lastFocusableId =
+ previousState.focusables[previousState.focusables.length - 1].id;
+
+ const previousFocusableId = this.findPreviousFocusable(previousState);
+
+ return {
+ activeFocusId: previousFocusableId || lastFocusableId
+ };
+ });
+ };
+
+ addFocusable = (id: string, {autoFocus}: {autoFocus: boolean}): void => {
+ this.setState(previousState => {
+ let nextFocusId = previousState.activeFocusId;
+
+ if (!nextFocusId && autoFocus) {
+ nextFocusId = id;
+ }
+
+ return {
+ activeFocusId: nextFocusId,
+ focusables: [
+ ...previousState.focusables,
+ {
+ id,
+ isActive: true
+ }
+ ]
+ };
+ });
+ };
+
+ removeFocusable = (id: string): void => {
+ this.setState(previousState => ({
+ activeFocusId:
+ previousState.activeFocusId === id
+ ? undefined
+ : previousState.activeFocusId,
+ focusables: previousState.focusables.filter(focusable => {
+ return focusable.id !== id;
+ })
+ }));
+ };
+
+ activateFocusable = (id: string): void => {
+ this.setState(previousState => ({
+ focusables: previousState.focusables.map(focusable => {
+ if (focusable.id !== id) {
+ return focusable;
+ }
+
+ return {
+ id,
+ isActive: true
+ };
+ })
+ }));
+ };
+
+ deactivateFocusable = (id: string): void => {
+ this.setState(previousState => ({
+ activeFocusId:
+ previousState.activeFocusId === id
+ ? undefined
+ : previousState.activeFocusId,
+ focusables: previousState.focusables.map(focusable => {
+ if (focusable.id !== id) {
+ return focusable;
+ }
+
+ return {
+ id,
+ isActive: false
+ };
+ })
+ }));
+ };
+
+ findNextFocusable = (state: State): string | undefined => {
+ const activeIndex = state.focusables.findIndex(focusable => {
+ return focusable.id === state.activeFocusId;
+ });
+
+ for (
+ let index = activeIndex + 1;
+ index < state.focusables.length;
+ index++
+ ) {
+ if (state.focusables[index].isActive) {
+ return state.focusables[index].id;
+ }
+ }
+
+ return undefined;
+ };
+
+ findPreviousFocusable = (state: State): string | undefined => {
+ const activeIndex = state.focusables.findIndex(focusable => {
+ return focusable.id === state.activeFocusId;
+ });
+
+ for (let index = activeIndex - 1; index >= 0; index--) {
+ if (state.focusables[index].isActive) {
+ return state.focusables[index].id;
+ }
+ }
+
+ return undefined;
+ };
 }