# Storybook SDC Addon
This addon streamlines the integration of Drupal Single Directory Components (SDC) into Storybook, allowing YAML-configured components (e.g., `*.component.yml`) to be dynamically loaded as stories in Storybook.
[](https://gyazo.com/2dcfa650c961679430d45eef24a82ab8)
## Table of Contents
- [Overview](#overview)
- [Storybook Example Live](#storybook-example-live)
- [Features of the Addon](#features-of-the-addon)
- [Quickstart Guide](#quickstart-guide)
- [Configuration](#configuration)
- [Creating Stories](#creating-stories)
- [Support for Single Story Files (\*.story.yml)](#support-for-single-story-files-storyyml)
- [Namespaces](#namespaces)
- [Drupal Icon API](#drupal-icon-api)
- [Advanced Grouping and Nesting](#advanced-grouping-and-nesting)
- [Regular Storybook](#regular-storybook)
- [Configuration Options](#configuration-options)
- [Setting Default Values](#setting-default-values)
- [Story Configuration via thirdPartySettings.sdcStorybook](#story-configuration-via-thirdpartysettingssdcstorybook)
- [UI Patterns](#ui-patterns)
- [Why Choose SDC Storybook Over Alternatives?](#why-choose-sdc-storybook-over-alternatives)
- [Dependencies](#dependencies)
- [Known Issues](#known-issues)
---
## Overview
This Storybook addon makes it easy to integrate Drupal Single Directory Components (SDC) into Storybook using YAML configurations and Twig templates. It dynamically loads components, allowing you to quickly create and manage stories with minimal configuration.
**It is still regular Storybook** but now with the added option to import and manage Drupal Single Directory Components (SDC).
## Storybook Example Live
You can view a [live example of the SDC Addon in Storybook](https://iberdinsky-skilld.github.io/sdc-addon), hosted on GitHub Pages, showcasing components in the `/components` directory of that repository.
## Features of the Addon
The SDC Storybook Addon simplifies the integration of Drupal Single Directory Components (SDC) into Storybook, offering several key features:
- **Vite Plugin Integration**: You can use either the vite-plugin-twig-drupal plugin (Twig.js) or the vite-plugin-twing-drupal plugin (Twing) to load and process Twig templates in SDC components.
- **Dynamic Path Resolution**: Utilizes namespaces to dynamically discover components within your project structure, eliminating the need for manual configuration.
- **Story Generation**: Automatically creates stories based on the YAML configurations of your SDC components, streamlining the story creation process.
- **JSON Schema Support**: Supports JSON Schema for props and slots, enabling the generation of mock data for missing values and ensuring data consistency.
- **Drupal Behavior Embedding**: Allows you to directly embed Drupal behaviors like `Drupal.attachBehaviors()` into Storybook previews, ensuring components behave similarly to their Drupal counterparts.
- **Custom and External Schema Definitions**: Supports custom and external JSON schema definitions to validate components based on Drupal-specific configurations (e.g., UI Patterns, Experience Builder).
- **Default and Custom Story Rendering**: Use `type: component` to nest components, `type: element` for HTML markup, and `type: image` for images within stories. Or create your own custom renderers.
- **Namespaces**: Supports multiple namespaces, allowing you to use components from different(parent/sibling) directories or packages.
- **Drupal Icon API**: Automatically detects `*.icons.yml` files in registered namespaces and makes `{{ icon('pack_id', 'icon_id', settings) }}` available in every Twig template. Supports `svg_sprite`, `svg` (inline), and `path` extractors with no configuration required.
## Quickstart Guide
1. **In theme or module or just empty directory (If package.json not yet exists)**:
```bash
npm init
echo "node_modules/" >> .gitignore
```
2. **Install dependencies**:
```bash
npm i vite twig storybook-addon-sdc --save-dev
```
3. **Initialize Storybook**:
```bash
npx storybook@latest init --builder vite --type html --no-dev
```
4. **Remove default storybook boilerplate stories (Optional)**:
```bash
rm -rf ./stories
```
5. **Configure as described in [Configuration](#configuration)**.
6. **Add components to the `components` directory** (or copy from this [repository](https://github.com/iberdinsky-skilld/sdc-addon/tree/main/components)).
7. **Set [type: module](https://nodejs.org/api/packages.html#type) in package.json:**
```json
{
"type": "module"
}
```
8. **Start Storybook**:
```bash
npm run storybook
```
## Configuration
To configure the addon, update `.storybook/main.js` as shown below:
You can use this plugin either with [Twig.js](https://github.com/twigjs/twig.js) or [Twing.js](https://twing.nightlycommit.com/) by setting the `twigLib` option to `'twig'` or `'twing'` in your configuration.
```js
import { join } from 'node:path' // 1. Add dependencies.
import { cwd } from 'node:process'
const config = {
stories: ['../components/**/*.component.yml'], // 2. Set components glob.
addons: [
{
name: 'storybook-addon-sdc', // 3. Configure addon.
options: {
sdcStorybookOptions: {
twigLib: 'twig', // 'twig' for Twig.js or 'twing' for Twing.
},
},
},
// Any other addons.
'@chromatic-com/storybook',
],
framework: {
name: '@storybook/html-vite',
options: {},
},
}
export default config
```
## Creating Stories
The `sdcStorybook` configuration in the SDC YAML file provides a flexible way to define custom stories for your components. This feature allows you to use predefined props, custom slots, or even reuse stories defined elsewhere. Here's how it works:
### Example Configuration
```yaml
thirdPartySettings:
sdcStorybook:
stories:
grid:
props:
label: Paragraph with grid
extra_classes:
- m-paragraph--grid
slots:
content:
# 1. Basic Props and Slots
# This card uses only the basic default props and slots defined in the component YAML.
- type: component
component: 'umami:card'
# 2. Predefined Story
# This card references an existing story (e.g., "Preview")
# from the component YAML, which includes predefined props and slots.
- type: component
component: 'umami:card'
story: Preview
# 3. Custom Props and Slots
# This card defines custom props to modify its behavior (e.g., setting
# the HTML tag to 'div') and custom slots to override specific content.
- type: component
component: 'umami:card'
props:
html_tag: 'div' # Custom HTML tag for the card container
slots:
content: 'Hello from third grid card!'
```
### How It Works in Practice
The addon dynamically renders the components and stories as defined:
- **Basic Args:** The default `Basic.args` of the `umami:card` component are used.
- **Existing Story:** The `Preview` story is loaded, ensuring consistency across the Storybook environment.
- **Custom Slots and Props:** Overrides the default slots and props behavior with unique content for that instance.
[](https://gyazo.com/7212a3f44052ebde34b59a1555d96afe)
## Core and custom story node types
Plugin supports 3 core story node types: `component`, `element`, and `image`.
Use `component` to nest other components within your story.
```yaml
type: component
component: 'umami:badge'
```
Use `element` to embed HTML markup within a specific tag.
```yaml
type: element
value: 'Hello World!'
attributes:
class: custom-class
```
Use `image` to embed images into your story.
```yaml
type: image
uri: https://placehold.co/1200x400
attributes:
class: custom-class
```
Example of using `element` and `image` in a story:
```yaml
thirdPartySettings:
sdcStorybook:
stories:
preview:
slots:
content:
# Result:
#
Hello
- type: element
tag: 'h2'
value: 'Hello'
attributes:
class: 'custom-class'
# Result:
#
- type: image
uri: 'https://placehold.co/600x400'
attributes:
class: 'custom-class'
```
### You can add custom renderers for additional `story` node types.
For example, to render a custom `icon` type:
```yaml
- type: icon
icon: arrow
```
Add the following to your `sdcStorybookOptions`:
```js
sdcStorybookOptions: {
...
storyNodesRenderer: [
{
appliesTo: item => item?.type === 'icon',
render: item =>
JSON.stringify(
``
),
priority: -4,
},
],
...
}
```
## Docs addon?
The storybook docs addon works out of the box.
## Support for Single Story Files (`*.story.yml`)
In addition to stories defined inside `*.component.yml` files, the addon now supports standalone story files with the `.story.yml` extension.
This means you can create independent stories for your components by simply adding a `.story.yml` file in your component directory. These files are automatically discovered and indexed by Storybook, allowing you to organize and share stories outside of the main component YAML.
**Example:**
```yaml
# components/slider/slider.badges.story.yml
name: Badges
slots:
slides:
- type: component
component: 'umami:badge'
props:
icon: timer
slots:
text: Hello
- type: component
component: 'umami:badge'
props:
icon: serves
slots:
text: Bonjour
- type: component
component: 'umami:badge'
props:
icon: difficulty
slots:
text: Ciao
```
## Namespaces
Namespace logic mirrors the behavior of Drupal themes and modules. This means your namespaces can be used:
In Twig as `namespace:component`:
```twig
{% include 'umami:title' %}
```
And in story definitions within YAML files:
```yaml
- type: component
component: 'umami:title'
```
### Namespace definitions:
- **Default Namespace**: The addon works out of the box without requiring namespace configuration and will use the current directory name as the default namespace, mirroring the behavior of a Drupal theme or module.
For example, if your `package.json` is in the `my-theme` directory, the default namespace will be `my-theme`, and this namespace will be linked to the `./components` directory.
- **Custom Namespace**: If you want to use a custom namespace or explicitly set the namespace, you can specify it in the plugin configuration:
```js
sdcStorybookOptions: {
...
namespace: 'umami',
},
```
- **Multiple Namespaces**: The most powerful feature is the ability to use multiple namespaces.
This allows you to use components from other directories (parent or sibling).
These directories must also contain a `/components` directory with SDC components.
```js
import { resolve } from 'node:path'
sdcStorybookOptions: {
namespaces: {
'parent-namespace': resolve('../parent-namespace'),
'grandparent-namespace': resolve('../../grandparent-namespace'),
},
},
```
Due to the specifics of the indexer implementation, you also need to duplicate the component paths in the `stories` array:
```js
stories: [
'../components/**/*.component.yml',
'../../parent-namespace/components/**/*.component.yml',
'../../../grandparent-namespace/components/**/*.component.yml',
],
```
- **Non Component Namespaces**: If you want to use components from a directory that does not follow the SDC structure (i.e., does not have a `components` directory), you can define a namespace that points directly to that directory. For example, if you have an `assets` directory with SVG icons:
```js
sdcStorybookOptions: {
namespaces: {
'assets': join(cwd(), './assets'),
},
},
```
In this case, the addon will look for components directly in the specified directory.
And you can use them in twig and stories as usual:
```twig
{% include '@assets/icons/example.svg' %}
```
## Drupal Icon API
The addon automatically supports Drupal's [Icon API](https://www.drupal.org/docs/develop/drupal-apis/icon-api) (introduced in Drupal 11.1). No configuration is required — as soon as a `{namespace}.icons.yml` file is found next to the `components/` directory of any registered namespace, the `icon()` Twig function becomes available in every template.
```twig
{{ icon('pack_id', 'icon_id') }}
{{ icon('pack_id', 'icon_id', { size: 'sm', class: 'my-icon' }) }}
```
### `{namespace}.icons.yml`
Place the file alongside the `components/` directory (i.e. the theme/module root):
```
my-theme/
├── components/
│ └── button/
│ └── button.component.yml
├── icons/
│ ├── sprite.svg
│ └── svg/
│ ├── home.svg
│ └── star.svg
└── my-theme.icons.yml ← discovered automatically
```
### Extractors
Three extractors are supported, matching Drupal core. A single pack file can contain any mix:
```yaml
# my-theme.icons.yml
# svg_sprite — single sprite file; icons referenced via