npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-keys

v3.0.0-rc20

Published

Simple way to bind keyboard to react thinking with flux

Downloads

44

Readme

React Keys

Simple way to bind keyboard to react with redux.

Build Status npm version codecov.io

Why ?

The need a fast way to bind keys to a react-powered UI with awesome redux for state management.

Installation

react-keys requires React 15 or later

npm install react-keys or yarn add react-keys

Dependencies

While not having direct dependencies, react-keys have to be used with react, react-dom and redux :

yarn add react
yarn add react-dom
yarn add redux

Link it with Redux (Otherwise it doesn't work !)

import { keysInit, keyReducer, getCurrentBinderId } from 'react-keys';
import { createStore, combineReducers } from 'redux';
import { connect } from 'react-redux';
import PureMosaic from '../PureMosaic'; // Pure React Component

//ONE
const store = createStore(
  combineReducers({
    '@@keys': keysReducer, // you need to link the react-keys reducer with the @@keys id
  })
);

//TWO
keysInit({ store: store }); // add the store there

//THREE
const Mosaic = connect(() => getCurrentBinderId()())(PureMosaic); // listen every changes of your mosaic like that

keysInit (object)

This is the entry point you need to define your redux store here. You can also define global behaviors

  • store (redux store / mandatory) Link the redux store to react-keys
  • eventCb (function / optional) Define a callback triggered when short/long press are done
  • debounce (number / optional) define a global debounce in ms, it can be overrided by components (default : 10)
  • config (object / optional) define keys to work with, this is the core concept for Keys components and it works as below
  • longPressTouch (array / optional) define list of keycode active for long press handling ( default : [37, 38, 39, 40])

The default config of react-keys is

{
  left: 37,
  up: 38,
  right: 39,
  down: 40,
  enter: 13,
}

You can get your computed config by calling like that

import { config } from 'react-keys';
const getConfig = () => config();

You can use them by adding a prop to Keys component with the keyword on before the key with CamelCase (onBack, onUp, onEnter...) You can extend this config by adding your own object config that will extend the default config.

Principles

react-keys has two main Component to deal with keyboard : Keys and Binder. Keys is basically an handler for keydown that execute a callback from a specific key. Binder helps you to navigate throw lists with spacial context. You can mount has much as Keys or Binder you want at same time but there is just one handler triggered by key action. By default the priority is given to the lastest Component mounted. You can configure that by setting a priority property on Keys and Binder. That means a Binder with priority 1 mounted before a Keys with priority 0 (default) will still trigger the action. When a Keys or Binder is unmonted, react-keys will figure out which Component will take the lead.

Keys

Very basic way to handle keyboard events. Yet is pretty powerfull :-)

import { Keys } from 'react-keys';

function onBack() {
  alert('alert bro');
}

const Component = ({ isActive }) => {
  return (
    <>
      <Keys
        id="rk-basic"
        onBack={() => console.log('Did I just push A ?')}
        active={isActive}
      />
      <h1>Check that out !</h1>
    </>
  );
};

<Keys ..options/>

  • id (string / mandatory) component id
  • on${keyCode} (function / optional) keyCode callback
  • active (boolean / optional) determine is Keys component is active (default true)
  • debounce (number / optional) define a debounce for keys press in ms (default global debounce)
  • priority (number / optional) define the priority from others (default 0)

Catcher

A basic component that can execute a callback when observing a sequence. This component has two props:

  • sequence (string / mandatory) the sequence to observe.
  • cb (function / mandatory) the callback to execute.
import { Catcher } from 'react-keys';

const ComponentWithCatcher = () => {
  return (
    <div>
      <Catcher
        sequence="424242"
        cb={() => console.log('Yeah ! Cheat code activated')}
      />
    </div>
  );
};

// When 42 is enter 3 times
// It will print on console 'Yeah ! Cheat code activated'

Binder

Fancy React component to deal with space navigation. It handles communication with multiple Binder compoments to create something great !

import { Binder, keysInit } from 'react-keys';

keysInit(); // must call it once at the app starting to enable the triggering

function renderWithId(id) {
  ReactDOM.render(
    <Mosaic binderId="mosaic-1" selectedId={id} />,
    document.getElementById('body')
  );
}

function onKey(element) {
  renderWithId(element.id);
}

const Card = ({ id, active }) => {
  const style = active ? 'selected' : '';
  return (
    <li id={id} className={style}>
      #{id}
    </li>
  );
};

const Mosaic = ({ binderId, selectedId }) => {
  return (
    <Binder
      id={binderId}
      active={true}
      onLeft={onKey}
      onUp={onKey}
      onDown={onKey}
      onRight={onKey}
    >
      <ul>
        <Card id={binderId + '-1'} active={selectedId === binderId + '-1'} /> //
        element need a unique id
        <Card id={binderId + '-2'} active={selectedId === binderId + '-2'} />
        <Card id={binderId + '-3'} active={selectedId === binderId + '-3'} />
      </ul>
    </Binder>
  );
};

renderWithId('mosaic-1-1');

<Binder ...options />

  • id (string / mandatory) Define the binder id
  • active (boolean / optional) determine if binder is active (default false)
  • selector (string / optional) DOM selector which define each element (default li)
  • priority (number / optional) define priority among others binders when mouting (default 0)
  • wrapper (string / optional) DOM selector which define parent element (default document)
  • filter (string / optional) class name which exclude element
  • debounce (number / optional) define a debounce for keys press in ms (default global debounce)
  • memory (boolean / optional) define if binder state has to be saved on unmounting (default false)
  • strategy (string / optional) define strape strategy on enter: start / mirror / none (default none)
  • refreshStrategy (string / optional) define how the focus behave on binder elements update (which element will be focused): first / previous (default first)
  • position (string / optional) to better handle for enterStrategy (vertial/horizontal) (default horizontal)
  • visibilityOffset (number / optional) set an offset un pixel to determine if an element is visible or hidden (default 0)
  • direction (string / optional) give a hint to react-keys to know if the direction is mainly horizontal or vertical (default none)
  • gap (number / optional) reduce or increase elements margin (default 0)`
  • boundedGap (number / optional) reduce or increase bounded margin (default 0)
  • triggerClick (boolean / optional) elements will trigger a click event on enter event (default true)`
  • topGap (number / optional) reduce or increase last top margin (default 0)
  • longPress (boolean / optional) active long press handler (default true)
  • rightGap (number / optional) reduce or increase last right margin (default 0)
  • leftGap (number / optional) reduce or increase last left margin (default 0)
  • downGap (number / optional) reduce or increase last down margin (default 0)
  • onRight (function / optional) callback for right events function(nextElement)
  • onLeft (function / optional) callback for left events function(nextElement)
  • onUp (function / optional) callback for up events function(nextElement)
  • onDown (function / optional) callback for down events function(nextElement)
  • onEnter (function / optional) callback for enter events function(nextElement)
  • onRightExit (function/string / optional) triggered when right event would go outside the elements block, it can be a function or the binder id we want to reach
  • onLeftExit (function/string / optional) triggered when left event would go outside the elements block, it can be a function or the binder id we want to reach
  • onUpExit (function/string / optional) triggered when up event would go outside the elements block, it can be a function or the binder id we want to reach
  • onDownExit (function/string / optional) triggered when down event would go outside the elements block, it can be a function or the binder id we want to reach

Example

import { Binder, keysSelector } from 'react-keys';

const PureMosaic = ({ selectedId, marginTop, marginLeft }) => {
  return (
    <Binder
      id="rk-binder"
      wrapper="#myWrapper"
      gap={20}
      onEnter={element => console.log(`ENTER with ${element.id}`)}
    >
      <div id="myWrapper">
        <ul style={{ marginTop: marginTop, marginLeft: marginLeft }}>
          <li id="1" className={selectedId === '1' ? 'selected' : ''}>
            #1
          </li>
          <li id="2" className={selectedId === '2' ? 'selected' : ''}>
            #2
          </li>
          <li id="3" className={selectedId === '3' ? 'selected' : ''}>
            #3
          </li>
          <li id="4" className={selectedId === '4' ? 'selected' : ''}>
            #4
          </li>
          <li id="5" className={selectedId === '5' ? 'selected' : ''}>
            #5
          </li>
          <li id="6" className={selectedId === '6' ? 'selected' : ''}>
            #6
          </li>
        </ul>
      </div>
    </Binder>
  );
};

const Mosaic = connect(() => ({
  selectedId: getCurrentSelectedId()(),
  marginTop: getBinderMarginTop('rk-binder')(),
  marginLeft: getBinderMarginLeft('rk-binder')(),
}))(PureMosaic); // listen every changes of your mosaic like that

the keys store will manage the state of each binders (no matter how many they are).

Selectors

Selectors give you easy control on your data binder, here few selectors for common use. they return a function

  • isCurrentBinder(binderId) determine if your binder is the current binder
  • isBinderActive(binderId) determine if your binder is active
  • getBinderMarginLeft(binderId) determine marginLeft of a binder
  • getBinderMarginTop(binderId) determine marginTop of a binder
  • getBinderSelectedId(binderId) determine selectedId of a binder
  • getCurrentSelectedId() get selected id of current active binder
  • getCurrentBinder() get state of current active binder
  • getCurrentBinderId() get id of current active binder
  • getBinders() get an array of all binders
  • getKeyCode() get key code currently pressed
  • isLongPress() determine if it is a long press
  • isVisibleInBinder(binderId, elementId) determine if an element is visible inside its binder

Action launchers

  • activeBinder(binderId, selectedId(optional)) activate a new binder by giving its id (first id by default)
  • resetBinder(binderId, selectedId(optional)) reset binder by giving its id (first id by default)
  • updateBinder(binderState) when you want to update the state manually (you must know what you do !)
  • removeBinder(binderId) remove a binder from the app state, useful when you want re-init the binder

Keys/Binder blockers

For some reason you want sometime block a specific binder or a specific key, you can perform that with these functions. Don't forget to unblock when you block :-)

  • bock(values or array of values(optional)) it can be keyCode or binderId. when no argument are passed, it blocks everything.
  • unblock(values or array of values(optional)) it can be keyCode or binderId. when no argument are passed, it unblocks everything.
  • blockExcept(values or array of values) it can be keyCode or binderId. Note when you want toi except a binder, you have to refers its keyCode associated
blockExcept('binderId', [
  config().down,
  config().up,
  config().left,
  config().right,
  config().enter,
]);
  • unblockExcept(values or array of values) it can be keyCode or binderId.

HOC

  • catcher(sequence, callback) it trigger the callback when a string sequence is catched

Tests

npm run test