@o3r/storybook NPM

This package is an Otter Framework Module.

Description

The Otter Framework provides several tools for Otter based projects.

!CAUTION Deprecated package @o3r/storybook package is deprecated and will no longer be updated as of Otter v12.

Description

The Otter Framework provides 3 sets of tools for Storybook integration:

Generators: To generate basic Story and set up the application to support Storybook
Stories helpers: to create story controllers based on Otter framework
AddOns: to add features to interact with Otter Customization

These tools are part of the @o3r/storybook package

Setup Storybook support

Otter framework provides 2 mechanisms to setup Storybook on an application/library:

When starting a new Application/Library

When creating a new application/library (ng new), the Otter Framework can be added with the ng add @o3r/core command. When executing this command, the following question will be asked: Add storybook setup? (default value: yes). If yes is chosen, Storybook mandatory configurations will be automatically added.

Storybook mandatory configurations

Storybook will require 2 files in the folder .storybook added into the root folder of the project.

main.js: partial webpack configuration used by Storybook to build the stories. It is used by Otter to add custom CSS (including theming variables)
preview.js: set of functions and default configurations used by the Storybook before displaying a component preview. This is used by Otter to load metadata (configuration, localization and styling) to set up the component controllers and integrate localization into the display.

For more documentation regarding the Storybook setup, your can refer to Storybook documentation.

Otter AddOns

To facilitate the customization of an Otter component, 2 Storybook Addons are provided.

Global Theming tab

(1): To facilitate the administration of global theming of a component, a tab has been added to the default storybooks tabs.
(2): Each global theme variable is editable
(3): 3 action buttons are provided
- Theme switching button (visible only in case of multi theme configured). See Multi Theme section.
- Theme override download button to download the CSS generated from the edited values.
- Reset button to remove override.

Exporter

3 different exports are available:

Export Theme: exports global theme as CSS file.
Export Configuration: exports component configuration as JSON file.
Export Component style: exports component variable override as CSS file.

Stories Helpers

Otter provides 3 helpers to generate automatically the component controllers. Each helper should be used in both preview.js to initialize the value and in <component>.stories.ts file to retrieve the value.

Setter (in preview.js)	Setter parameter(s)	Extractor (in stories)	Extractor Parameter(s)
setStyleMetata: register styling metadata	styling metadata extracted by `@o3r/styling` from the application/library.In case of library, a default theme should be provided	extractStyling: retrieve styling variable configuration for the component	component selector used as CSS variable name prefix in the component
setConfiguratiobnMetadata: register the configuration metadata	configuration metadata extracted by `@o3r/configuration` from the application/library.	extractConfiguration: retrieve dynamic configuration's configuration for the component	library name: name of the current library/component which the component is attached to.component name: class name of the current component
setLocalizationMetadata: register the localization metadata	localization metadata extracted by `@o3r/localization` from the application/library.	extractLocalization: retrieve full localization configuration for the component	translation: current component translations map

Find documentation to write a story on Storybook documentation.

Additional features

Multi theming

The Theme Addon is supporting multi theme and allows the user to switch from one theme to another. The list of themes should be provided as global parameter with a key/value map: