@24i/bigscreen-sdk 1.0.32 → 1.0.33-alpha.2548

package/packages/keyboard/README.md

@@ -1,237 +1,237 @@
----
-id: README
-title: Keyboard
-hide_title: true
-sidebar_label: Keyboard
----
-
-# Keyboard
-This package holds various keyboard implementations.
-
-List of available keyboards:
-- DefaultKeyboard
-- MobiKeyboard
-- AndroidKeyboard
-- WhitelabelKeyboard
-
-## Props
-All default values are general. Each keyboard implementation can change this default behaviour.
-For details, check your keyboard implementation code.
-```typescript
-/**
- * Sets the layout of the keyboard. Set by keyboards but adjustable if needed.
- * @default provided by keyboard implementation
- */
-layouts?: Record<Layouts, KeyMatrixCell[][]>,
-/**
- * { x, y } index of the first key to focus.
- * @default provided by keyboard implementation
- */
-initialFocus?: Index2D,
-/**
- * Whether the keyboard should initially render as hidden.
- * @default true
- */
-initiallyIsHidden?: boolean,
-/**
- * Whether the keyboard should handle key digits pressed on the remote control or HW keyboard.
- * @default true
- */
-handleRemoteDigits?: boolean;
-/**
- * Whether the keyboard should handle keys pressed on HW keyboard.
- * @default true
- */
-handleHWKeyboard?: boolean;
-/**
- * Circular navigation of the keyboard.
- * @default CircularDirection.HORIZONTAL
- */
-circular?: CircularDirection;
-/**
- * Whether the keyboard should hide if mouse/pointer clicks outside of keyboard.
- * @default true
- */
-shouldHideOnBackdropClick?: boolean;
-/**
- * Mode in which shift key operates.
- * @default ShiftMode.COMBINED
- */
-shiftMode?: ShiftMode,
-```
-
-### ShiftMode
-The mode in which the shift key operates.
-- SHIFT_ONLY - The first key after the shift key is uppercase. Then it switches back to lowercase.
-Pressing shift again just turns it off.
-- CAPS_ONLY - All keys after pressing the shift key are uppercase until the shift key is pressed again.
-- COMBINED - If pressed once, it behaves as Shift, first letter is uppercase, other are lowercase.
-If pressed twice it behaves as CapsLock, all keys are uppercase. Third press returns to lowercase.
-
-`ShiftMode` union can be imported from `@24i/bigscreen-sdk/keyboard/ShiftMode`;
-
-## Usage
-```tsx
-import { ime } from '@24i/bigscreen-sdk/ime';
-import { Keyboard } from '@24i/bigscreen-sdk/keyboard/DefaultKeyboard';
-
-class App extends Component {
-    componentDidMount() {
-        ime.setKeyboard(this.keyboard.current);
-    }
-
-    render() {
-        return (
-            // App JSX
-            <Keyboard ref={this.keyboard} />
-        );
-    }
-}
-```
-
-## Disabling MRCU interaction with scene elements during inputting
-When inputting, rest of the scene elements are not accessible with MRCU device,
-because of `keyboard-backdrop` element. It is stretched by default to the whole
-screen behind keyboard elements. If you need to move it or change it,
-you can do it with your own `keyboard-backdrop` class style.
-
-### Mobi keyboard
-
-```tsx
-import { ime } from '@24i/bigscreen-sdk/ime';
-import { CircularDirection } from '@24i/bigscreen-sdk/focus';
-import { Keyboard } from '@24i/bigscreen-sdk/keyboard/MobiKeyboard';
-
-class App extends Component {
-    componentDidMount() {
-        ime.setKeyboard(this.keyboard.current);
-    }
-
-    render() {
-        return (
-            // App JSX
-            <Keyboard
-                ref={this.keyboard}
-                texts={{ clear: '', ... }} // Texts for buttons like clear, cancel, done etc.
-                circular={CircularDirection.ALL} // Read more in Focus readme, passed directly to matrix
-                layout={{ // Can contain custom keyboard layouts
-                    normal: [
-                        ['1', '2', ...],
-                        ['q', 'w', ...],
-                        ['a', 'b', ...],
-                        ['z', 'x', ...],
-                    ],
-                    special: [
-                        ['+', ...],
-                        ['!', ...],
-                        ['$', ...],
-                        ['~', ...],
-                    ]
-                }}
-                focusMatrix={{
-                    normal: [...], // Similar to layout, but has extra strings for default buttons: done, clear, special, backspace, space, left, right, cancel, shift
-                    special: [...], // Similar to layout, same extra strings as normal focus matrix
-                }}
-            />
-        );
-    }
-}
-```
-
-### Android Keyboard
-
-Keyboard is fully based on MobiKeyboard, the only difference is styling and layout.
-
-```tsx
-import { Keyboard } from '@24i/bigscreen-sdk/keyboard/AndroidKeyboard';
-```
-
-### Whitelabel Keyboard and Whitelabel Numeric keyboard
-
-These keyboards are expected to be customizable using the backstage.
-If you do not use backstage, you must import default Whitelabel styles.
-
-```tsx
-import { ime } from '@24i/bigscreen-sdk/ime';
-import { CircularDirection } from '@24i/bigscreen-sdk/focus';
-import { Keyboard } from '@24i/bigscreen-sdk/keyboard/WhitelabelKeyboard';
-import { hebrew } from '@24i/bigscreen-sdk/keyboard/Whitelabel/layouts';
-import { NumericKeyboard } from '@24i/bigscreen-sdk/keyboard/WhitelabelNumericKeyboard';
-
-// default styles import
-import '@24i/bigscreen-sdk/keyboard/WhitelabelKeyboard/WhitelabelStyles';
-import '@24i/bigscreen-sdk/keyboard/WhitelabelNumericKeyboard/WhitelabelStyles';
-
-class App extends Component {
-    componentDidMount() {
-        ime.setKeyboard(this.keyboard.current);
-        // or
-        ime.setKeyboard(this.numericKeyboard.current);
-    }
-
-    render() {
-        return (
-            <Keyboard
-                ref={this.keyboard}
-                circular={CircularDirection.NONE}
-                layout={{
-                    normal: [
-                        ['1', '2', ...],
-                        ['q', 'w', ...],
-                        ['a', 'b', ...],
-                        ['z', 'x', ...],
-                    ],
-                    special: [
-                        ['+', ...],
-                        ['!', ...],
-                        ['$', ...],
-                        ['~', ...],
-                    ]
-                }}
-                texts={{
-                    toNormalLayout: 'Abc',
-                    toSpecialLayout: '+/#',
-                    space: 'Space',
-                    domain: '.com',
-                    clear: 'Clear',
-                    continue: 'Continue',
-                }}
-                initialFocus={{ x: 5, y: 2 }}
-                languageLayout={hebrew} // Switchable language layout
-            />
-            <NumericKeyboard
-                ref={this.numericKeyboard}
-                circular={CircularDirection.NONE}
-                texts={{
-                    clear: 'Clear',
-                    continue: 'Continue',
-                }}
-                initialFocus={{ x: 0, y: 0 }}
-            />
-        )
-    }
-}
-```
-
-## Contributing
-If you wish to add custom keyboard to this package, it will be nice addition to the collection.
-1. Create a folder for your keyboard in `src`.
-2. Add your implementation
-3. Add `YouKeyboardName.ts` file to the package root with reexport from your `src/YourKeyboardName` folder so the app could easily import only your implementation.
-
-### Tips
-There is no base for the Keyboard as it is expected that keyboards will extend `Component`.
-You need to implement `IKeyboard` interface from 'ime' package.
-
-There are several utils that you can use to make implementing the keyboard easier:
-- Matrix - use this component from focus to handle your focus needs.
-- generateFocusMatrixFromStringMatrix - takes object with key references and string matrix and prepares ref matrix to be used with Matrix
-- input/insertCharAtCaret - inserts char at current caret position to given input
-- input/backspace - removes the char in front of the current caret position
-- input/del - removes the char after the current caret position
-- caret/caretLeft - moves caret to the left
-- caret/caretRight - moves caret to the right
-- caret/caretHome - moves caret to the beginning
-- caret/caretEnd - moves caret to the end
-
-Look at the code of existing keyboards for inspiration on where to start.
+---
+id: README
+title: Keyboard
+hide_title: true
+sidebar_label: Keyboard
+---
+
+# Keyboard
+This package holds various keyboard implementations.
+
+List of available keyboards:
+- DefaultKeyboard
+- MobiKeyboard
+- AndroidKeyboard
+- WhitelabelKeyboard
+
+## Props
+All default values are general. Each keyboard implementation can change this default behaviour.
+For details, check your keyboard implementation code.
+```typescript
+/**
+ * Sets the layout of the keyboard. Set by keyboards but adjustable if needed.
+ * @default provided by keyboard implementation
+ */
+layouts?: Record<Layouts, KeyMatrixCell[][]>,
+/**
+ * { x, y } index of the first key to focus.
+ * @default provided by keyboard implementation
+ */
+initialFocus?: Index2D,
+/**
+ * Whether the keyboard should initially render as hidden.
+ * @default true
+ */
+initiallyIsHidden?: boolean,
+/**
+ * Whether the keyboard should handle key digits pressed on the remote control or HW keyboard.
+ * @default true
+ */
+handleRemoteDigits?: boolean;
+/**
+ * Whether the keyboard should handle keys pressed on HW keyboard.
+ * @default true
+ */
+handleHWKeyboard?: boolean;
+/**
+ * Circular navigation of the keyboard.
+ * @default CircularDirection.HORIZONTAL
+ */
+circular?: CircularDirection;
+/**
+ * Whether the keyboard should hide if mouse/pointer clicks outside of keyboard.
+ * @default true
+ */
+shouldHideOnBackdropClick?: boolean;
+/**
+ * Mode in which shift key operates.
+ * @default ShiftMode.COMBINED
+ */
+shiftMode?: ShiftMode,
+```
+
+### ShiftMode
+The mode in which the shift key operates.
+- SHIFT_ONLY - The first key after the shift key is uppercase. Then it switches back to lowercase.
+Pressing shift again just turns it off.
+- CAPS_ONLY - All keys after pressing the shift key are uppercase until the shift key is pressed again.
+- COMBINED - If pressed once, it behaves as Shift, first letter is uppercase, other are lowercase.
+If pressed twice it behaves as CapsLock, all keys are uppercase. Third press returns to lowercase.
+
+`ShiftMode` union can be imported from `@24i/bigscreen-sdk/keyboard/ShiftMode`;
+
+## Usage
+```tsx
+import { ime } from '@24i/bigscreen-sdk/ime';
+import { Keyboard } from '@24i/bigscreen-sdk/keyboard/DefaultKeyboard';
+
+class App extends Component {
+    componentDidMount() {
+        ime.setKeyboard(this.keyboard.current);
+    }
+
+    render() {
+        return (
+            // App JSX
+            <Keyboard ref={this.keyboard} />
+        );
+    }
+}
+```
+
+## Disabling MRCU interaction with scene elements during inputting
+When inputting, rest of the scene elements are not accessible with MRCU device,
+because of `keyboard-backdrop` element. It is stretched by default to the whole
+screen behind keyboard elements. If you need to move it or change it,
+you can do it with your own `keyboard-backdrop` class style.
+
+### Mobi keyboard
+
+```tsx
+import { ime } from '@24i/bigscreen-sdk/ime';
+import { CircularDirection } from '@24i/bigscreen-sdk/focus';
+import { Keyboard } from '@24i/bigscreen-sdk/keyboard/MobiKeyboard';
+
+class App extends Component {
+    componentDidMount() {
+        ime.setKeyboard(this.keyboard.current);
+    }
+
+    render() {
+        return (
+            // App JSX
+            <Keyboard
+                ref={this.keyboard}
+                texts={{ clear: '', ... }} // Texts for buttons like clear, cancel, done etc.
+                circular={CircularDirection.ALL} // Read more in Focus readme, passed directly to matrix
+                layout={{ // Can contain custom keyboard layouts
+                    normal: [
+                        ['1', '2', ...],
+                        ['q', 'w', ...],
+                        ['a', 'b', ...],
+                        ['z', 'x', ...],
+                    ],
+                    special: [
+                        ['+', ...],
+                        ['!', ...],
+                        ['$', ...],
+                        ['~', ...],
+                    ]
+                }}
+                focusMatrix={{
+                    normal: [...], // Similar to layout, but has extra strings for default buttons: done, clear, special, backspace, space, left, right, cancel, shift
+                    special: [...], // Similar to layout, same extra strings as normal focus matrix
+                }}
+            />
+        );
+    }
+}
+```
+
+### Android Keyboard
+
+Keyboard is fully based on MobiKeyboard, the only difference is styling and layout.
+
+```tsx
+import { Keyboard } from '@24i/bigscreen-sdk/keyboard/AndroidKeyboard';
+```
+
+### Whitelabel Keyboard and Whitelabel Numeric keyboard
+
+These keyboards are expected to be customizable using the backstage.
+If you do not use backstage, you must import default Whitelabel styles.
+
+```tsx
+import { ime } from '@24i/bigscreen-sdk/ime';
+import { CircularDirection } from '@24i/bigscreen-sdk/focus';
+import { Keyboard } from '@24i/bigscreen-sdk/keyboard/WhitelabelKeyboard';
+import { hebrew } from '@24i/bigscreen-sdk/keyboard/Whitelabel/layouts';
+import { NumericKeyboard } from '@24i/bigscreen-sdk/keyboard/WhitelabelNumericKeyboard';
+
+// default styles import
+import '@24i/bigscreen-sdk/keyboard/WhitelabelKeyboard/WhitelabelStyles';
+import '@24i/bigscreen-sdk/keyboard/WhitelabelNumericKeyboard/WhitelabelStyles';
+
+class App extends Component {
+    componentDidMount() {
+        ime.setKeyboard(this.keyboard.current);
+        // or
+        ime.setKeyboard(this.numericKeyboard.current);
+    }
+
+    render() {
+        return (
+            <Keyboard
+                ref={this.keyboard}
+                circular={CircularDirection.NONE}
+                layout={{
+                    normal: [
+                        ['1', '2', ...],
+                        ['q', 'w', ...],
+                        ['a', 'b', ...],
+                        ['z', 'x', ...],
+                    ],
+                    special: [
+                        ['+', ...],
+                        ['!', ...],
+                        ['$', ...],
+                        ['~', ...],
+                    ]
+                }}
+                texts={{
+                    toNormalLayout: 'Abc',
+                    toSpecialLayout: '+/#',
+                    space: 'Space',
+                    domain: '.com',
+                    clear: 'Clear',
+                    continue: 'Continue',
+                }}
+                initialFocus={{ x: 5, y: 2 }}
+                languageLayout={hebrew} // Switchable language layout
+            />
+            <NumericKeyboard
+                ref={this.numericKeyboard}
+                circular={CircularDirection.NONE}
+                texts={{
+                    clear: 'Clear',
+                    continue: 'Continue',
+                }}
+                initialFocus={{ x: 0, y: 0 }}
+            />
+        )
+    }
+}
+```
+
+## Contributing
+If you wish to add custom keyboard to this package, it will be nice addition to the collection.
+1. Create a folder for your keyboard in `src`.
+2. Add your implementation
+3. Add `YouKeyboardName.ts` file to the package root with reexport from your `src/YourKeyboardName` folder so the app could easily import only your implementation.
+
+### Tips
+There is no base for the Keyboard as it is expected that keyboards will extend `Component`.
+You need to implement `IKeyboard` interface from 'ime' package.
+
+There are several utils that you can use to make implementing the keyboard easier:
+- Matrix - use this component from focus to handle your focus needs.
+- generateFocusMatrixFromStringMatrix - takes object with key references and string matrix and prepares ref matrix to be used with Matrix
+- input/insertCharAtCaret - inserts char at current caret position to given input
+- input/backspace - removes the char in front of the current caret position
+- input/del - removes the char after the current caret position
+- caret/caretLeft - moves caret to the left
+- caret/caretRight - moves caret to the right
+- caret/caretHome - moves caret to the beginning
+- caret/caretEnd - moves caret to the end
+
+Look at the code of existing keyboards for inspiration on where to start.