@anovel/tachyon v0.9.3

Tachyon

Helpers to be used within a frontend framework.

yarn add @anovel/tachyon

A light framework for easier and advanced DOM manipulations.

• OS
• Url
  • goTo
  • isActive
  • buildUrl
• Keys
  • Sequencer.update
  • Sequencer.remove
  • Sequencer.clear
  • Sequencer.keys
• RecordsManager
  • RecordsManager.undo
  • RecordsManager.redo
  • RecordsManager.push
  • RecordsManager.clearAll
  • RecordsManager.content

OS

Get the current running OS.

import {getOS, literals} from '@anovel/tachyon';

const myOS = getOS();

if (myOS === literals.OS.MACOS) {
  // Do something.
}

getOS may return any of the following strings (all can be found in literals.OS):

Url

goTo

Extra implementation of url navigator with options.

import {goTo} from '@anovel/tachyon';

// Basic example
goTo('/foo/bar', history); // opens '/foo/bar' in current tab

// With flags
goTo('/foo/bar', history, {openOutside: true}); // opens '/foo/bar' in a new browser tab
goTo('/foo/bar', history, {skip: true}); // opens '/foo/bar' in current tab, and remove previous location from history

// Using url build options
goTo('/foo/:param', history, {params: {param: 'bar'}}); // opens '/foo/bar'
goTo('/foo/bar', history, {query: {uid: 'user_id'}}); // opens '/foo/bar?uid=user_id'
goTo('/foo/bar', history, {anchor: 'section2'}); // opens '/foo/bar#section2'

Arguments

(1) You can read more about routers at this link.

Options

Additional parameters are available to perform your navigation.

isActive

Check if the current route is active.

import {isActive} from '@anovel/tachyon';

// Retrieve your current location from the most convenient way
// (window.location or the react-router location property).
let location;

// The following examples will assume that current location 
// pathname is '/foo/bar/qux'.

console.log(isActive('/foo/bar', location)); // true
console.log(isActive('/foo/qux', location)); // false
console.log(isActive('/foo/bar', location, true)); // false

// You can also check multiple routes at once by passing an array as first argument.
console.log(isActive(['/foo/qux', '/foo/bar'], location)); // true

Trailing slashes are ignored, so /foo/bar and /foo/bar/ will be treated the same, weather in target or currentLocation. Also, if leading slash is missing, it will be added automatically.

Arguments

buildUrl

Build an url from a template string and parameters.

import {buildUrl} from '@anovel/tachyon';

buildUrl('/foo'); // '/foo'
buildUrl('/foo/:param1', {param1: 'bar'}); // '/foo/bar'
buildUrl('/foo/:param1', {param1: 'bar'}, {uid: 'user_uid'}); // '/foo/bar?uid=user_id'
buildUrl('/search', null, {genre: 'books', priceMax: 10}); // '/search?genre=books&priceMax=10'

Arguments

Keys

A sequencer allows you to listen for keypress on any html element and trigger actions whenever a combo is hit.

import React from 'react';
import {Sequencer, literals} from '@anovel/tachyon';
import css from 'myStyle.module.css';

// Example with a copy/paste mock implementation.
const MyComponent = () => {
  const sequencer = new Sequencer();
  
  const combos = [
    {trigger: literals.COMBOS.COPY, action: () => console.log('I am copied!')},
    {trigger: literals.COMBOS.PASTE, action: () => console.log('I am paste!')}
  ];
  
  return (
    <div className={css.container}>
      <div
        onKeyDown={sequencer.update({combos})}
        onKeyUp={sequencer.remove}
      >Copy me (CTRL + C) or Paste me (CTRL + V)</div>
    </div>
  );
};

The Sequencer constructor does not take any arguments. Instead, every parameters are passed on the go through its methods, which allows for highly dynamic behavior.

Sequencer ships with 4 public methods.

• Sequencer.update
• Sequencer.remove
• Sequencer.clear
• Sequencer.keys

Sequencer.update

Update sequence and return the updated list of pressed keys in the sequence. Return the current pressed keys array.

function handler(e) {
  const keys = sequencer.update(options)(e);
}

Arguments

Options

Combo

Sequencer.remove

Remove all occurences of a keycode from the sequence. Takes a KeyboardEvent as argument. Return the current pressed keys array.

function handler(e) {
  const keys = sequencer.remove(e);
}

Sequencer.clear

Empty (reset) the current key chain.

sequencer.clear();

Sequencer.keys

Return the current pressed keys array.

const keys = sequencer.keys();

RecordsManager

Manage a record history for textual inputs from pure javascript.

import {RecordsManager} from '@anovel/tachyon';

const manager = new RecordsManager('');

Constructor Arguments

Constructor Options

import {RecordsManager} from '@anovel/tachyon';

// Do not keep more than 100 records in history.
const manager1 = new RecordsManager('', {maxLength: 100});

const baseHistory = [{
  newContent: 'hello',
  caret: {start: 0, end: 0}, 
  oldContent: '', 
  timestamp: 1613609752021
}];

// Will start with value 'hello'.
const manager2 = new RecordsManager('', {history: baseHistory});

// Will start with value ''. This is a bad utilization since history record do not match the actual state.
const manager3 = new RecordsManager('', {history: baseHistory, trustStartValue: true});

// Good utilization of above case : the history records match the current state.
const manager4 = new RecordsManager('hello world', {history: baseHistory, trustStartValue: true});

StaticRecord

import {RecordsManager} from '@anovel/tachyon';

const baseHistory = [{
  newContent: 'hello ',
  caret: {start: 0, end: 0}, 
  oldContent: '', 
  timestamp: 1613609752021
}, {
  newContent: 'world',
  caret: {start: 6, end: 6},
  oldContent: '',
  timestamp: 1613609754927,
  canceled: true
}];

// Will start with value 'hello '.
const manager = new RecordsManager('', {history: baseHistory});

console.log(manager.redo()); // hello world

PackOption

Define rules for merging records together when they are 'close enough'.

import {RecordsManager} from '@anovel/tachyon';

const manager = new RecordsManager('', {pack: {maxSize: 2}});

// Type 'hello world'
manager.push({newContent: 'h', caret: {start: 0, end: 0}});
manager.push({newContent: 'e', caret: {start: 1, end: 1}});
manager.push({newContent: 'l', caret: {start: 2, end: 2}});
manager.push({newContent: 'l', caret: {start: 3, end: 3}});
manager.push({newContent: 'o', caret: {start: 4, end: 4}});
manager.push({newContent: ' ', caret: {start: 5, end: 5}});
manager.push({newContent: 'w', caret: {start: 6, end: 6}});
manager.push({newContent: 'o', caret: {start: 7, end: 7}});
manager.push({newContent: 'r', caret: {start: 8, end: 8}});
manager.push({newContent: 'l', caret: {start: 9, end: 9}});
manager.push({newContent: 'd', caret: {start: 10, end: 10}});

console.log(manager.content()); // 'hello world'
console.log(manager.undo()); // 'hello worl'
console.log(manager.undo()); // 'hello wo'
console.log(manager.undo()); // 'hello '
console.log(manager.undo()); // 'hell'

import {RecordsManager} from '@anovel/tachyon';

// Break on spaces (words).
const manager = new RecordsManager('', {pack: {separators: [' ']}});

// Type 'hello world'
manager.push({newContent: 'h', caret: {start: 0, end: 0}});
manager.push({newContent: 'e', caret: {start: 1, end: 1}});
manager.push({newContent: 'l', caret: {start: 2, end: 2}});
manager.push({newContent: 'l', caret: {start: 3, end: 3}});
manager.push({newContent: 'o', caret: {start: 4, end: 4}});
manager.push({newContent: ' ', caret: {start: 5, end: 5}});
manager.push({newContent: 'w', caret: {start: 6, end: 6}});
manager.push({newContent: 'o', caret: {start: 7, end: 7}});
manager.push({newContent: 'r', caret: {start: 8, end: 8}});
manager.push({newContent: 'l', caret: {start: 9, end: 9}});
manager.push({newContent: 'd', caret: {start: 10, end: 10}});

console.log(manager.content()); // 'hello world'
console.log(manager.undo()); // 'hello '
console.log(manager.undo()); // ''

import {RecordsManager} from '@anovel/tachyon';

// Break after 600ms.
const manager = new RecordsManager('', {pack: {timeout: 600}});

// Type 'hello world'
manager.push({newContent: 'h', caret: {start: 0, end: 0}});
manager.push({newContent: 'e', caret: {start: 1, end: 1}});
manager.push({newContent: 'l', caret: {start: 2, end: 2}});
manager.push({newContent: 'l', caret: {start: 3, end: 3}});
manager.push({newContent: 'o', caret: {start: 4, end: 4}});

// wait 1s.
await new Promise(resolve => setTimeout(resolve, 1000));

manager.push({newContent: ' ', caret: {start: 5, end: 5}});
manager.push({newContent: 'w', caret: {start: 6, end: 6}});
manager.push({newContent: 'o', caret: {start: 7, end: 7}});
manager.push({newContent: 'r', caret: {start: 8, end: 8}});
manager.push({newContent: 'l', caret: {start: 9, end: 9}});
manager.push({newContent: 'd', caret: {start: 10, end: 10}});

console.log(manager.content()); // 'hello world'
console.log(manager.undo()); // 'hello'

Caret

RecordsManager.undo

Undo the last active entry. Returns the altered content.

import {RecordsManager} from '@anovel/tachyon';

const manager = new RecordsManager('');

const baseHistory = [{
  newContent: 'hello ',
  caret: {start: 0, end: 0},
  oldContent: '',
  timestamp: 1613609752021
}, {
  newContent: 'world',
  caret: {start: 6, end: 6},
  oldContent: '',
  timestamp: 1613609754927
}];

// Will start with value 'hello world'.
const manager = new RecordsManager('', {history: baseHistory});

console.log(manager.undo()); // 'hello '

RecordsManager.redo

Undo the first inactive entry. Returns the altered content.

import {RecordsManager} from '@anovel/tachyon';

const manager = new RecordsManager('');

const baseHistory = [{
  newContent: 'hello ',
  caret: {start: 0, end: 0},
  oldContent: '',
  timestamp: 1613609752021
}, {
  newContent: 'world',
  caret: {start: 6, end: 6},
  oldContent: '',
  timestamp: 1613609754927,
  canceled: true
}];

// Will start with value 'hello '.
const manager = new RecordsManager('', {history: baseHistory});

console.log(manager.redo()); // 'hello world'

RecordsManager.push

Add a record to history. Returns the altered content.

import {RecordsManager} from '@anovel/tachyon';

const manager = new RecordsManager('');

const baseHistory = [{
  newContent: 'hello ',
  caret: {start: 0, end: 0},
  oldContent: '',
  timestamp: 1613609752021
}];

// Will start with value 'hello '.
const manager = new RecordsManager('', {history: baseHistory});

console.log(manager.push({newContent: 'world', caret: {start: 6, end: 6}})); // 'hello world'

RecordsManager.clearAll

Clear history. Cannot be recovered.

import {RecordsManager} from '@anovel/tachyon';

const manager = new RecordsManager('');

const baseHistory = [{
  newContent: 'hello ',
  caret: {start: 0, end: 0},
  oldContent: '',
  timestamp: 1613609752021
}];

// Will start with value 'hello '.
const manager = new RecordsManager('', {history: baseHistory});

manager.cleanAll();

console.log(manager.undo()); // 'hello ' since last entry was lost and cannot be undone.

RecordsManager.content

Returns the current string content.

import {RecordsManager} from '@anovel/tachyon';

const manager = new RecordsManager('');

const baseHistory = [{
  newContent: 'hello ',
  caret: {start: 0, end: 0},
  oldContent: '',
  timestamp: 1613609752021
}];

// Will start with value 'hello '.
const manager = new RecordsManager('', {history: baseHistory});

console.log(manager.content()); // 'hello '

License

Licensed under MIT for A-Novel.