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

Alias	Description	Status
DecimalInput	An input for enforcing a decimal value	Stable
DateInput	An input for selecting a date value	Stable
ResponsiveNav		Development
CheckboxInput	An input for toggling between two states	Stable
SelectInput		Planning
PasswordInput		Planning
FullScreenNav		Planning
SliderInput		Planning

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}>
	);
}

Property	Type	Default	Required	Description
className	String	null	no	A String to be used for the html class attribute for the component and all sub-components
disabled	Boolean	false	no	A Boolean for disabling access to the input
onBlur	Function	null	no	A Function to call on `onBlur`
onFocus	Function	null	no	A Function to call on `onFocus`
places	Number	2	no	The number of decimal places to which the decimal value should be restricted
setValue	Function	n/a	yes	A Function for setting the decimal value to state or for passing it to an action
value	Number	null	no	A number value to set the input to (useful for chaining inputs). Can also be used to set an initial value

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>
	);
}

Property	Type	Default	Required	Description
className	String	null	no	A String to be used for the html class attribute for the component and all sub-components
dayNames	String Array	['Su', 'Mo'...]	no	An Array of strings to display as the days of the week on the calendar beginning with Sunday
firstDoW	Number	1	no	The first day of the week beginning with Sunday = 0, ending with Saturday = 6
format	String	'YYYY-MM-DD'	no	A String representing the format for displaying the selected date
monthNames	String Array	['Jan', 'Feb'...]	no	An Array of strings to display as the months of the year on the calendar beginning with January
setValue	function	n/a	yes	A Function for setting the full-date value back to state or for passing it to an action
today	String	'Today'	no	The text to use for the today button
value	String	new Date()	no	A date to set the input to. Can be used to set an initial value