Psammead is a package library which contains a mixture of components, containers and utilities.
Psammead packages are split into:
- Components - GEL-compliant presentational React components built on
styled-components
. They are ready for use out of the box, regardless of data source. - Containers - Functional components for optional use with presentational components of the same name.
- Utilities - Commonly shared Psammead dependencies, fundamentals to aid building additional GEL-compliant components, and aditional packages for use in building SPAs.
Please familiarise yourself with our:
- Code of conduct
- Code Standards and Ways of Working
- Contributing guidelines
- Guide to Code Reviews
- Github Project Board Guide
- Primary README (you are here)
- Talos (package bumping bot)
- Use/consumption of Psammead packages guidelines and package list
- Things to do when creating a new component
NB there is further documentation colocated with relevant packages and code. The above list is an index of the top-level documentation of our repo (and our sibling repo Simorgh).
git clone [email protected]:bbc/psammead.git
cd psammead && npm run install:packages
N.B. When merging branches, the npm run install:packages
command should be favoured over npm install
. More details available here.
Install dependencies locked to package-lock.json
:
npm run ci:packages
(NB: You can't reliably run the jest tests when the packages are linked locally, as they may have been linked across breaking changes. Running npm run ci:packages
resets all links. To update snapshots within unit tests, run npm run test:unit -- -u
.)
Run the component tests:
npm test
This runs Jest across any packages matching this glob pattern: packages/components/**/*.test.jsx
. It also runs each package's npm test
command if it is defined
npm run storybook
NB, we've defined global styles (normalize, box-sizing, Reith font) in the Storybook config so that components render as expected.
npm run build
Learn how to use Psammead components in your own project.
We strive for components to conform to the following minimum levels of support, but please check each component's individual README.
Browser | Lowest version |
---|---|
Safari | 9 |
Chrome | 53 |
Edge | 37 |
Firefox | 45 |
IE | 11 |
Opera | 40 |
Opera Mini | 18 |
Android Browser | 7 |
Android Chrome | 53 |
Android Firefox | 49 |
IOS Safari | 10 |
Note that these browser support levels have been defined by usage statistics for BBC News and BBC Persian.
Software | Version | Type | Browser |
---|---|---|---|
ZoomText | Latest | screen magnifier | Internet Explorer 11 |
Dragon NaturallySpeaking | 13 | speech recognition | Internet Explorer 11 |
JAWS | 17 | screen reader | Internet Explorer 11 |
Read&Write | Latest | screen reader | Internet Explorer 11 |
VoiceOver | Latest | screen reader | Safari on iOS |
NVDA | Latest | screen reader | Firefox on Windows |
Testing instructions for each assistive technology, including priority categories.
- Create an npm account with your bbc email address. https://www.npmjs.com
- In your npm profile settings, set up Two Factor Authentication. Enable it for authorization and publishing
- Back up your recovery codes for your account
- Join the BBC npm org by following the process here: https://github.com/bbc/npm When you're added to the org and signed in, you should be able to see all public and private
@bbc
packages here: https://www.npmjs.com/settings/bbc/packages
Packages are published on merge into the latest
branch via our CI process. The process defaults to publishing with public
access and a tag of latest
, however this can be overridden using configuration on your package json.
To stop your package from publishing to NPM add the following value to your package.json
"private": true,
The access and tag of the release can be overridden from the default values by adding the following values to your package.json
"publishConfig": {
"access": "restricted",
"tag": "alpha",
}
The access value is restricted by NPM and can only be the values public
and restricted
.
The Psammead Storybook is hosted on GitHub pages at http://bbc.github.io/psammead. It is currently deployed via a local script that builds Storybook to the gh-pages
git branch which is used by GitHub pages.
npm run deploy-storybook
NB, this automatically pushes to the 'gh-pages' branch, which deploys to the live GitHub pages site. Please only run this script on the latest
branch.
Pronounced as sam-me-ad
'sรฆmiห|รฆd
"The Psammead, also known as Sand Fairy, is a sapient magical creature once encountered by five children in a gravel pit".
It MIGHT stand for:
Perfectly sharable atomically modular magically engineered abstract doodads
Or it might be named Psammead to follow the mythical creature theme of related repos.
We'll let you decide!