wix-incubator / wix-react-tools

(DEPRECATED) Utilities and helpers to build stunning react components

Wix React Tools

This project is deprecated

This library provides helpful utilities and features for React components.

Notice

Current documentation (including this file) contains information matching the 3.1.x release, while the code is an advanced release candidate of 4.0.0. the changes between 3.1.x and 4.0.0 are yet only roughly documented in the Changelog.

Installation

Install wix-react-tools as a dependency in your local project.

Using npm:

npm install wix-react-tools --save

Using yarn:

yarn add wix-react-tools

@next version

To obtain the latest beta version, use the @next tag:

npm install wix-react-tools@next --save

React Component Features

A React Component Feature is a function that takes a component and returns a component with all the characteristics of the original component, plus one or more new features.

More details in React Component Features

properties feature

Connects some common component properties to the component's render output.

More details in properties feature

stylable feature

Applies a stylable stylesheet to a component, Allowing it to use the stylesheet's class and state names natively.

More details in stylable feature

disposable feature

Helps manage clean-ups according to the lifecycle of the component.

More details in disposable feature

decorateReactComponent

decorateReactComponent offers a way of applying hooks to React components in order to implement various features. These hooks temporarily monkey-patch React.createElement, React.cloneElement, and cloneElement (to be added soon) in order to customize every element created by your component. Further reading in decorateReactComponent

global ID

Produce unique ID values for react components More details in global ID

chainFunctions

Accept two function arguments. Returns a new function that when executed calls the two functions, one after the other with the same arguments, and returns void.

chainFunctions.cached

To avoid unnecessary render calls when using this utility to produce a property, the cached modifier is a memoized version, meaning calling it twice with the same arguments will produce the same result.

function chainFunctions<T extends Function>(first:T, last:T):T
function chainFunctions.cached<T extends Function>(first:T, last:T):T & {clear():void}

disposers

The Disposers class is helpful in keeping track of disposer functions and clearing them when needed.

More details in disposers

function-decor

Wrapping library for functions.

More details in function-decor

class-decor

Hooks library for ES6 classes

More details in class-decor

private-state

Privately extend any object, without inheritance or visibility concerns.

More details in private-state

configuration

Static configuration allows passing any form of data/flags to tools.

More details in config

dev mode

Constant values to use for configuring development mode on or off, and synchronizes the config's development flag with process.env.NODE_ENV.

More details in dev mode

developer documentation

how to build and test

• clone the repository
• in the cloned folder, run npm install
• run npm test to build and test the code in both nodejs and browser

how to debug (browser)

• run npm start to run a development server
• open http://localhost:8080/webtest.bundle to run live tests that will update while you change the source code

how to contribute new features

1. open an issue describing the use-case for the feature.
2. in that issue, explain how a user may solve the problem without the solution, describe the solution design, and the reasoning behind it.
3. after agreeing on a solution design, start a branch with github reference to the issue.
4. add a markdown ("readme") description of the feature in the docs, containing the feature's description, user-code level examples, and API documentation of the feature.
5. write acceptance tests for the feature, including all the documented code examples. If strong typings are part of the feature's requirements, add tests in the typings-checker folder as well.
6. implement the feature, add tests as needed.
7. when the feature seems complete, open a pull request (PR) with github reference to the issue.

how to contribute bug fixes

The process is similar to that of new features, only the bar of explanations and documentations may be lower. start by opening an issue describing the bug.

wix-react-tools's Issues

add black list for root helper

implement `mouse-toucher`

• add method this.mouseToucher(handler) to component.
• update docs

Test API typings with typings-checker

https://www.npmjs.com/package/typings-checker

re-order arguments in class-decor API to allow functional

class should be last arguments, method name before it

Stuff not exported from proj

config and private context cannot actually be used like in the docs (via import ... from 'react-bases)
cuz there is no export for them
Example-test and tests should all import from '../src' and not go any deeper

documentation for context and privateState

extract documentation of context from readme to its own file,
document private state

add console warning when middleware doesn't call next (flag on/off in config)

make debugger-friendly class names in dev-mode

in dev-mode, instead of using naive ES6 code to create a sub-class with a static name, use Function constructor to dynamically define the inherited class using the name of the original class.

references:

• Dynamic function names in JavaScript
• Mutable example for named inheritence

transform class-decor documentation

split to separate files
rewrite to fit actual API

create function decor

(refactor) : extract the before-after-middleware mechanism from class decor, so it can be used directly on any function outside the context of a class

Add 'Flags'

• add flags
• document flags.ts

add `copy-aria`

copy only the following from props to root:

• aria-label
• aria-labelledby
• aria-describedby

see docs as reference of original design

add `onclickoutside`

see docs

add simple usage examples (build regression)

make sure all decorators infer types on simple use cases

add registerForRootElement

Add registerForRootElement to handle various cases where the hook should only run on the root node of the component (e.g. copy classNames, event handlers, etc..).

add `props-injection`

see docs

also read Convention: Pass Unrelated Props Through to the Wrapped Component

re-structure projecrt

the project contains several layers of code under different assumptions, most of them are not (yet) relevant.

restructure it for clarity and focus

add `langauges`

see docs
(Yuri has some good libraries)

rewrite `global-id` mixin

Tom: updating to reflect broken down task phases

Phase 0 - Decorator allows the direct usage of getGlobalId(), assures instance determinism and global uniqueness

• - Add the getGlobalId method to component prototype
• - On instance creation store random key for uniqueness (using private context)

Phase 1 - @getGlobalId() decorator automatically converts id attributes with global determinism

• - TBD

Phase 2 - Root handling and inheritence

• - TBD

see docs and implementation

add @mixin class-decor decorator

decorate class T with class D.
accept argument of class D, and return a decorator that applies it via using a private state, adding @onInstance(...) with the constructor and @add(..) with each method.

add private context class decorator

add a decorator that provides a private context per instance
should replace the need for options.datakey:

data key

allows mixins to store data for a mixed class instance

should be generated using generateKey

example

import {before,after,generateKey} from 'class-decor'


function logMethodPerf(methodName:string){
  return function(cls:typeof object){
    const mixinDataKey = generateKey('perfLogger');

    before(cls,
                   methodName,
                   function(instance:Logger,data,...methodArguments){
                      data.before = Date.now();
                      return methodArguments
                    },
                    {dataKey:mixinDataKey});


    after(cls,
                   methodName,
                   function(instance:Logger,data,result){
                      console.log(Data.now()-data.before)
                      return result
                    },
                    {dataKey:mixinDataKey});
  }

}

on click outside

when registering the click-outside to a child component:
onClickOutside needs to clean up (un-register from global) when:

1. the child unmounts
2. it is being replaced by another handler

that means the child has to have a willUnmount step, and a willReceiveProps state when it handles this kind of thing.
meaning, the subject is not a SFC.

measure and optimize

Use a real life application

add `.ifExists` modifier to method decorators

so that adding before(...) to a class that does not have the specified method will silently add it, but before.ifExists(...) will not create a method that is otherwise not there.

address/compare to mixins tools in the readme

specifically mixwith.js and mics. can we pass our decorators as "legal" mixins to their DSL?

(class decor) support regular expressions instead of method names

useful for AOP decorators like logging, timing etc.

copy / merge event handlers

catch all on* functoin properties and copy/merge them to root.

add 'copyEventHandlers'

copyEventHandlers is used for the purpose of copying any event handlers defined externally, and setting them on the component's root.

• Add spec documentation
• Implement with tests

concat data-automation-id values

data-automation-id specifically needs to be merged the same way as className

rewrite `observable-component` base

• document (see here for reference)
• extract mixin(s)

see old implementation for details

add `registerForCreateElement`

see
https://github.com/wix/react-bases/blob/master/docs/react-mixer.md#registerforcreateelement

add `@add` decorator

see docs

add `merge-class-names`

see docs

use global unique ID

use utility method to generate Symbols (or symbols-like strings).
implement usage in tils/private-context.ts/getPrivateContext

add `merge-inline-style`

see docs

update dependencies

since @Greenkeeper does not work on this project, manually test and update dependencies

add `copy-data-attributes`

see docs

productize mixins engine

core mixins API

• documentation page with simple motivations
• document mutation of original class
• document core decorators:
  • add
  • (add) onClass - runs once per class on first instance creation
  • onInstance
  • (add) mix - gets another class as argument, combines add and onInstance. perhaps instanceOf hook?

method hooks

• documentation page with simple motivations
• document API hooks:
  • before
  • middleware
  • after
• explain order of execution: before/middleware/after, parent/child, decoration order

add `safe-global-events`

see docs

explain remark in `root-handler.spec.ts`

I can't make sense of the remark // todo: prolly needs to throw an error in root-handler.spec.ts

@tomrav could you shed some light?

support more than one instance per class

make multi-key cache and use for event merging

a construct of weak maps that can take two (or more?) items as keys.
order does matter

• use this to cache the result of merging two event handlers for task #72

support abstract classes

currently our typings do not support decorating abstract classes.

rewrite `disposable`

re-implement it using class-decor

see docs

handle inheritance tree of decorators

Not the main use case right now

@mix1
class Super {}

@mix2
class Child1 extends Super{}

class Child2 extends Super{} // mix2 applies! This is not the expected behavior

document method hooks order logic

before / after / middleware, who decorated first, who decorated a parent etc.

(dev mode feature) add warn if `after` change result of method to `undefined`

when in dev-mode (use config module), if an after hook receives a non-undefined lastResult argument and returns undefined - add a console warning.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because we are using your CI build statuses to figure out when to notify you about breaking changes.

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

If you have already set up a CI for this repository, you might need to check your configuration. Make sure it will run on all new branches. If you don’t want it to run on every branch, you can whitelist branches starting with greenkeeper/.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

after acts as 'ifExists'

• Fix error Cannot read property 'apply' of undefined to something meaningful
• Fix after to do what it should

implement `addToProto`

adds a method to the prototype of a class (overridable, more performant than a middleware)

if a user overrides the method, in dev mode issue a console warning