ink-tree-focus
v0.2.0
Published
Focus manager for Ink that follows the component tree structure
Downloads
7
Maintainers
Readme
Ink Tree Focus
This package for Ink manages focus similarly to Ink focus but it does by respecting the tree structure, instead the creation order.
Install
npm install ink-tree-focus
Basic Usage
Lets analyze the following basic example:
import React from 'react';
import { Box, BoxProps, render, Text, useApp, useInput } from 'ink';
import { FocusInputCapture, FocusManagerProvider, useFocusManager } from 'ink-tree-focus';
interface IFocusableItemProps extends BoxProps {
children: React.ReactNode;
}
const FocusableItem = ({ children, ...boxProps }: IFocusableItemProps) => {
const { focusRef, isFocused } = useFocusManager();
return (
<Box {...boxProps} ref={focusRef}
borderStyle='round'
borderColor={isFocused ? 'red' : ''}
>
{children}
</Box>
);
};
const App = () => {
const { exit } = useApp();
const { focusRef } = useFocusManager({ isFocusable: false });
useInput((input, key) => {
if (input === 'q') {
exit();
}
});
return (
<>
<Text>Use Tab / shift + Tap to move</Text>
<Box ref={focusRef} flexDirection="row">
<FocusableItem><Text>Box 1</Text></FocusableItem>
<FocusableItem><Text>Box 2</Text></FocusableItem>
<FocusableItem flexDirection="column">
<Text>Box 3</Text>
<Box flexDirection="row">
<FocusableItem><Text>1</Text></FocusableItem>
<FocusableItem><Text>2</Text></FocusableItem>
</Box>
</FocusableItem>
<FocusableItem><Text>Box 4</Text></FocusableItem>
</Box>
<Text>Press q to quit</Text>
</>
);
};
render(
<FocusManagerProvider>
<FocusInputCapture>
<App />
</FocusInputCapture>
</FocusManagerProvider>,
);
First of all, the library provides (essentially) three objects:
FocusManagerProvider
: Used to provide the application the React's context provider with all the logic for the app. Must wrap the app, then you can forget about it.FocusInputCapture
: A predefined wrapper with the only purpose of bindtab
key to focus next element andshift + tab
to previous element. You can omite it and make your custom binding.useFocusManager
: The hook which provides all the resources to manage the focus system. That is the main of the library.
Also in the example we see the use of focusRef
, used to bind the DOMElement to the internal tree of focusables, and isFocused
, which tells if that DOMElement has currently the focus.
There are more concrete and useful items provide by the hook, which can be found in the API description.
Example
npm run example
API
Hook useFocusManager
Usage: const returned = useFocusManager(props)
where
props
is optional and has the optional members:
isFocusable
- Type
boolean
- Determines if this node can be focused.
- Type
focusRef
- Type
React.MutableRefObject<DOMElement | null>
- Type
and returned
provide the following information:
focusId
- Type:
Symbol
- A
Symbol
that identifies the focus node.
- Type:
focusRef
- Type:
{current: Ink.DOMElement}
- A reference (created with react's
useRef
) which component should reference to. That's needed to bind the DOMElement to a focusable node.
- Type:
isFocused
- Type:
boolean
- Determine if the refecenced element is focused or not.
- Type:
isDescendantFocused
- Type
boolean
- Determine if some estrictly descendant (not includes itself) element is focused.
- Type
activeId
- Type
Symbol | undefined
- The focusId of the currently focused node, if any.
- Type
and the following commands:
setFocus
- Type
(focusId: Symbol) => void
- Set focus to element with focus id
focusId
.
- Type
focusPrev
- Type
(focusId?: Symbol) => void
- Focus the previous node in preorder.
If
focusId
is provided, operation will be done with respectfocusId
, otherwise theactiveId
. IfactiveId
is not defined, it will focus last element.
- Type
focusNext
- Type
(focusId?: Symbol) => void
- Focus the next node in preorder.
If
focusId
is provided, operation will be done with respectfocusId
, otherwise theactiveId
. IfactiveId
is not defined, it will focus first element.
- Type
focusPrevChild
- Type
(focusId?: Symbol) => void
- Focus the previous child node in preorder.
If
focusId
is provided, operation will be done with respectfocusId
, otherwise theactiveId
. IfactiveId
is not defined in the relevant subtree, it will focus last element.
- Type
focusNextChild
- Type
(focusId?: Symbol) => void
- Focus the next child node in preorder.
If
focusId
is provided, operation will be done with respectfocusId
, otherwise theactiveId
. IfactiveId
is not defined in the relevant subtree, it will focus first element.
- Type
focusPrevSibling
- Type
(focusId?: Symbol) => void
- Focus the previous sibling node in preorder.
If
focusId
is provided, operation will be done with respectfocusId
, otherwise theactiveId
. IfactiveId
is not defined, nothing will happen.
- Type
focusNextSibling
- Type
(focusId?: Symbol) => void
- Focus the next sibling node in preorder.
If
focusId
is provided, operation will be done with respectfocusId
, otherwise theactiveId
. IfactiveId
is not defined, nothing will happen.
- Type
focusParent
- Type
(focusId?: Symbol) => void
- Focus the parent node in preorder.
If
focusId
is provided, operation will be done with respectfocusId
, otherwise theactiveId
. IfactiveId
is not defined, nothing will happen. If no parent node exists,activeId
will be set toundefined
.
- Type