carpentry v0.18.0

Carpentry

Carpentry is a library of highly customisable React components. The functionality and layout of each component is designed to be configurable via APIs using React props. All non-structural styling is left for the developer.

WARNING This package is under initial development. Until v1.0.0 all changes should be treated as breaking. Not recommended for production.

Rationale

Working to different style guides on different projects often means highly opinionated / pre-styled components can't be used. Developers can often reuse functionality but not styling even though the designs they are given usually conform to common user interface trends. All Carpentry components are designed to solve this problem by sticking to the following points:

• Components are functionally specialised, doing one job and doing it well
• Components can have their functionality configured easily via an API using React props
• Components have only structural styling included (no colours, fonts, padding etc.)
• Structural styling can be configured (e.g. a hamburger menu button on the left or the right)
• When necessary, components can nest other components

Installation

Thanks to NPM it's super easy, just npm install carpentry.

Usage

Carpentry is built to work with the Node.js require() function. All components have an alias as listed in the table above. The recommended way to access a component is via its alias:

var MyDecimalInput = require('carpentry').DecimalInput;

Building and Testing

Carpentry can be built and demonstrated by running one of the following commands:

• npm run clean - Clean the output directory.
• npm run build - Produce a build of the package.
• npm run bundle -- -c COMPONENT - Produce a demonstration bundle containing the specified component.
• npm run demo -- -c COMPONENT - Produce a demonstration bundle containing the specified component and open it in the default browser.

Components

Key: Stable - currently included, API is stable. Unstable - currently included, API still under development. Development - not included, in development. Planning - not yet in development.

DecimalInput

Use this component to enforce input of a decimal value. setValue should be a function that can set a value to state or pass it to an action. Using value, the component can also take a value for conversion or display purposes. This can be useful for chaining multiple inputs or applying your own validation.

setDecimal: function(decimal) {
	Actions.updateDecimal(decimal);
},

render: function() {
	return (
		<MyDecimalInput className="MyDecimalInput" setValue={this.setDecimal}>
	);
}

In addition to the props API above, you can also use the triggerKeypress method to pass a key (String) to the component. This is useful for simulating a keypress when implementing a soft keyboard. In order to access this method, add a ref to your DecimalInput and call the method via that ref.

DateInput

This component is useful for enforcing input of a valid full-date string. setValue should be a function that can set a date string back to state or pass it to an action. value can be used to set a default date or update the input.

setDate: function(date) {
	Actions.updateDate(date);
},

render: function() {
	return (
		<MyDateInput className="MyDateInput" setValue={this.setDate}>
			<img src="path/to/icon" alt="Date Input Icon" />
		</MyDateInput>
	);
}