carpentry
v0.18.0
Published
A library of highly customisable React components
Downloads
13
Readme
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>
);
}