This repository will contain the Influitive Pattern Lab as well as base css, and reusable js components.
Patternity is using the nodejs version of patternlab.io. Additional documentation for the pattern lab can be found at https://github.com/oscar-g/patternlab-node/tree/dev-gulp
Install patternity as a node module.
npm install --save patternity<@version:optional>
Note: be sure to install releases from npm, as these are versioned. if you install from influitive/patternity you will get the latest master, which may include breaking changes
Patternity JSX components can be included in a normal module bundler fashion by requiring components like so
var Alert = require('patternity/lib/alert');
Styles require a bit more work (until our whole build pipeline is on Webpack, at which point there's nothing extra to do).
To inform your build pipeline about the location of patternity's styles, you must add patternity's includePaths into the compilation step. You can achieve this like so:
// Gulp - gulpfile.js
gulp.task('sass', function () {
return gulp.src("application.scss", { base: './app/assets/stylesheets' })
.pipe(
sass({includePaths: require('patternity').includePaths})
)
.pipe(gulp.dest("public/assets");
});
// Webpack - webpack.config.js
// See https://github.com/jtangelder/sass-loader#sass-options for further instructions
function includePaths () {
var paths = require('patternity').includePaths;
return paths.map(function(p){
return ["includePaths[]=", p].join('');
}).join('&');
}
module.exports = {
// ... whatever config
module: {
loaders: [
{ test: /.scss$/, loader: "style!css!sass?" + includePaths() }
]
}
};
At this point, scss files can import patternity files using imports such as:
@import 'infl-styles/dependencies';
@import 'infl-styles/alert';
Note that the 'dependencies' requirement is due to SCSS's poor handling of duplicate imports whereby if each module (ie 'alert') were to import its dependencies, and you imported multiple of those modules, SCSS would actually duplicate the 'dependencies'.
Ideally we'd like each module to define its deps for composability, but for now we require that the app implementing patternity also import its dependencies (once), then whatever subsequent modules.
Most component are implemented using Facebook's React architecture.
Components are just required and mounted into you're own react code.
var Alert = require('lib/alert.jsx');
...
<Alert title="I'm a little teapot" >
<p>Short and stout</p>
</Alert>
It will create a basic stylesheet, index file, readme, and test file under 'src/test-component' to help get you started.
Please make sure you follow the style guide below if submitting a pattern to this repo.
- Use
camelCased
variable names instead ofsnake_cased
where possible - Install the eslint for your editor
- do
npm run githooks
to set up commit linting when cloning a new patternity repo
When creating a React component:
- Use
.jsx
as the extension - Place in the
infl-components
directory - Underscore delimited file names: e.g.
alert_box.jsx
- Class name must match file name, but camel cased: e.g.
AlertBox
The following command will create a basic component with the name TestComponent:
npm run create TestComponent
import React, { Component, PropTypes } from ''
class Greeter extends Component {
propTypes = {
name: PropTypes.string
}
defaultProps = {
name: 'Skye'
}
render() {
return <div>
{this._greeting()}
</div>;
}
_greeting() {
const { name } = this.props;
return `Hello, ${name}.`;
}
}
export default Greeter;
Always assign the created object to a local variable with same name as the class
class Greeter extends Component {
...
}
export default Greeter;
Also, make sure the component is exported so it's available to require
ing components.
In order to keep our components organized we place the methods and properties of a component in the following order:
- React lifecycle methods/properties
* e.g.
propTypes
,getDefaultProps
,componentDidMount
,componentWillUpdateProps
, etc. - The React
render
method - Local private methods
* All private methods must start with an underscore
_
, e.g._greeting
Your render
method should only return JSX.
See React Docs - Interactity and Dynamic UIs
There are generally two things you store in state, data and view state. Components which hold data are called View Controllers and usually exist near the top of your view hierarchy. These View Controllers will manage getting the data from the appropriate sources and handing it down to child views through props
.
View state are still variables held in a components state but generally relates to how the component should render on the screen. An internal state property on a collapsable section would manage the open/close state of the rendered elements.
A components props
are data that the component uses to render itself. Sometimes components have no props and just represent a reused visual component, but most times they handle some piece of data or other.
e.g.
<Icon icon={'search'} />
The Icon
component is here is taking a string to tell it which icon to render. Internally the component would have access to that string via this.props.icon
.
In general, the 'dumber' your components are, the easier they are to test, and the easier they are to compose. You should try to limit the amount of components which access your data layer, and these should also be generally limited to your View Controllers.
Also when updating a components state, always be sure to use this.setState()
instead of setting this.state
directly, since re-renders hinge of off state updates. Multiple calls to this.setState()
are batched for performance reasons, so calling this.setState()
6 times in a method is not a problem. However, since this.setState()
is batched, that makes changes to this.state
asynchronous, so be careful of accessing this.state
immediately after calling this.setState()
. See React Docs - setState
Notes:
- Components which don't render from state won't update if they are already mounted and just receive new props. It's up to the component writer to decide if the new props have changed enough to mandate a change. You have a chance to do this in the
componentWillReceiveProps
lifecycle method. You can also force a react component to re-render itself using thethis.forceUpdate
Reference:
Each component can have it's own Readme.md file. New components located in src
will have their Readme.md in their component directory. Older components have their readmes located in infl-components-examples
and the directory looks exactly like infl-components except the files end in .readme.md
instead.
Strict semantic versioning:
- Any change that breaks an existing api should bump the Major version
- Any added functionality should change the minor version
- Patch versions are reserved for changes transparent to the end user
Do not break this convention.
##Use git flow
- if you don't have it installed you can
brew install git-flow
- you can also do git-flow style manually, just remember to merge master back into dev after a release
- git flow setup:
git flow init
- accept the default for the first option (master)
- enter development for the second option (branch name for next release)
- set version tag prefix to 'v'
- accept defaults for all other options
Feature git workflow:
git flow feature start <feature-name>
this will create a new branch named feature/
develop you feature here and when it's done do:
git flow feature finish <feature-name>
this merges your feature into development
Hotfix worflow
git flow hotfix start <version-number>
this will create a new branch named hotfix/ develop your hotfix here and when it's done do:git flow hotfix finish <version-number>
this merges your hotfix into master
and tags the commit with 'v'
master is then back-merged into development
Release git workflow:
git flow release start <version-number>
this will create a new branch named release/
example git flow release start 1.0.62
-
run
npm version (major|minor|patch) --no-git-tag-version
Note: --no-git-tag-version is passed because git flow will be tagging the release -
git flow release finish <version-number>
you will be prompted to write a message for the tag, "Release version " should suffice, you will be writing more detail in github releases feature. this will tag master withv<version-number>
this will merge release/ into master as well as back merge the release into development (the version numbers will then match)
-
git push && git push --tags
You need to push the changes along with the associated new tag. -
Update tag information in GitHub
Once you have master at your desired release state, you can run npm publish
to publish to the npm registry
Patternlab resides here.
The pattern lab is built automatically by circleci. Results for old pattern lab are available at http://patternity.internal.influitive.com. The new pattern lab can be found at http://patternity.experimental.influitive.com.