@bbc/psammead-storybook-helpers v9.0.17
psammead-storybook-helpers -
This package provides a collection of common values that are used in storybook by the Psammead components.
Exports
TEXT_VARIANTS
- A list of text samples in different languages, with the script and direction that should be used for that language.
themes
- An object containing the Storybook themes we use.
withServicesKnob
- Is a function that returns a storybook decorator function that adds a Select a service
dropdown to the knobs panel. When a service is selected from the dropdown it does 2 things:
- Provides the decorated stories with the following properties that can be passed into components:
text
: A short string of text in the language of the chosen service.longText
: A long string of text in the language of the chosen service (we can use this to stress test components).dir
: The reading directionality of the chosen service e.g.ltr
orrtl
.script
: The chosen service's script typography settings e.g. the font-size and line-heights.service
: The name of the chosen service e.g.arabic
.variant
: The variant value of a chosen service, e.gserbianLat
will have variantlat
. Non variant service will default todefault
.articlePath
: A path to an article in the relevant service.selectedService
: The name of the selected service as it appears in the dropdown of available services.
- Toggles the layout directionality of the chosen service.
The withServicesKnob
function accepts an options argument with 2 properties:
defaultService
(String): The default selected service of the services dropdown e.g.arabic
. The default isnews
.services
(Array): A list of services that the dropdown will display. The default is all services.
buildRTLSubstories
- a function to create right-to-left variants of stories as substories. Internally it uses the withServicesKnob
to set the default service as arabic
.
The buildRTLSubstories
function accepts 2 arguments.
storyKind
(String) - This is the story kind that you want you want to create RTL substories from. This will normally be the first argument you pass intostoriesOf
e.g.storiesOf('Components/Paragraph', module)
. This parameter is required.options
(Object) - Available options:include
(Array) - A list of specific story names to create RTL substories of. If this is not provided then all stories will have RTL substories.
Installation
npm install @bbc/psammead-storybook-helpers --save-dev
Usage
TEXT_VARIANTS
import { select } from '@storybook/addon-knobs';
import { TEXT_VARIANTS } from '@bbc/psammead-storybook-helpers';
const label = 'Languages';
const defaultValue = 'This is a caption';
const groupIdentifier = 'CAPTION VARIANTS';
<Caption>
{select(label, TEXT_VARIANTS, TEXT_VARIANTS.news, groupIdentifier).text}
</Caption>;
withServicesKnob
storiesOf('Components/Paragraph', module)
.addDecorator(withKnobs)
.addDecorator(withServicesKnob()) // default selected service is `news`
.add('A paragraph with English text', ({ text, script, service }) => (
<Paragraph script={script} service={service}>
{text}
</Paragraph>
));
To set a default service:
storiesOf('Components/Paragraph', module)
.addDecorator(withKnobs)
.addDecorator(
withServicesKnob({
defaultService: 'arabic',
services: ['news', 'arabic', 'amharic'],
}),
) // default selected service is `arabic` and the available services in the dropdown are `news`, `arabic`, `amharic`
.add('A paragraph with Arabic text', ({ text, script, service }) => (
<Paragraph script={script} service={service}>
{text}
</Paragraph>
));
If you want to add this decorator to a single story rather than a series of stories as documented above, perhaps because you need each story to have a different default service, then you need to decorate each story directly instead of using the addDecorator
method. An example of how you could write this is shown below:
const arabicServiceDecorator = withServicesKnob({
defaultService: 'arabic',
});
const pashtoServiceDecorator = withServicesKnob({
defaultService: 'pashto',
});
storiesOf('Components/Paragraph', module)
.addDecorator(withKnobs)
.add('A paragraph with Arabic text', () =>
arabicServiceDecorator(({ text, script, service }) => (
<Paragraph script={script} service={service}>
{text}
</Paragraph>
)),
)
.add('A paragraph with Pashto text', () =>
pashtoServiceDecorator(({ text, script, service }) => (
<Paragraph script={script} service={service}>
{text}
</Paragraph>
)),
);
You can include links to articles in the relevant services and variants
const BASE_URL = 'https://www.bbc.com';
storiesOf('Components/Paragraph/Link', module)
.addDecorator(withKnobs)
.addDecorator(withServicesKnob()) // default selected service is `news`
.add(
'A paragraph with an inline link to an article',
({ text, script, service, articlePath }) => (
<Paragraph script={script} service={service}>
<InlineLink href={`${BASE_URL}${articlePath}`}>{text}</InlineLink>
</Paragraph>
),
);
The above example dismisses the use of the addDecorator
method and decorates the story directly.
buildRTLSubstories
import { buildRTLSubstories } from '@bbc/psammead-storybook-helpers';
// create RTL variants of all stories of a kind
buildRTLSubstories('Components/Paragraph');
import { buildRTLSubstories } from '@bbc/psammead-storybook-helpers';
// create RTL variants of specific stories of a kind
buildRTLSubstories('Components/Paragraph', {
include: ['containing an inline link'],
});
Contributing
When adding a new export to this utility package the export tests also need to be updated. When removing an exisiting export from this utility package the export tests need to be updated and the package version requires a major change (EG: 1.2.1 -> 2.0.0) as this would be considered a breaking change due to functionality being removed.
Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead respository.
Code of Conduct
We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.
License
Psammead is Apache 2.0 licensed.
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago