storybook-addon-sdc 0.1.22 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -34
- package/dist/preset.js +9 -14
- package/package.json +11 -9
package/README.md
CHANGED
|
@@ -5,6 +5,7 @@ This addon streamlines the integration of Drupal Single Directory Components (SD
|
|
|
5
5
|
[](https://gyazo.com/2dcfa650c961679430d45eef24a82ab8)
|
|
6
6
|
|
|
7
7
|
## Table of Contents
|
|
8
|
+
|
|
8
9
|
- [Overview](#overview)
|
|
9
10
|
- [Why Choose SDC Storybook Over Alternatives?](#why-choose-sdc-storybook-over-alternatives)
|
|
10
11
|
- [Features of the Addon](#features-of-the-addon)
|
|
@@ -21,6 +22,7 @@ This addon streamlines the integration of Drupal Single Directory Components (SD
|
|
|
21
22
|
---
|
|
22
23
|
|
|
23
24
|
## Overview
|
|
25
|
+
|
|
24
26
|
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.
|
|
25
27
|
|
|
26
28
|
## Why Choose SDC Storybook Over Alternatives?
|
|
@@ -28,65 +30,78 @@ This Storybook addon makes it easy to integrate Drupal Single Directory Componen
|
|
|
28
30
|
While solutions like [SDC Styleguide](https://www.drupal.org/project/sdc_styleguide) and [Drupal Storybook](https://www.drupal.org/project/storybook) are valuable, the SDC Storybook addon offers distinct advantages:
|
|
29
31
|
|
|
30
32
|
### 1. Component Independence and Modularity
|
|
31
|
-
|
|
32
|
-
-
|
|
33
|
+
|
|
34
|
+
- Following the **BEM (Block Element Modifier)** methodology, a component should work independently across environments.
|
|
35
|
+
- The functionality of your component must not depend on the **Drupal version**, or the active **Drupal theme** — it should be portable to **any** system.
|
|
33
36
|
|
|
34
37
|
### 2. No Complex Drupal Setup Required
|
|
35
|
-
|
|
36
|
-
|
|
38
|
+
|
|
39
|
+
- No need to install or configure Drupal dependencies for component development.
|
|
40
|
+
- Work faster by developing frontend components in Storybook without running a heavy Drupal instance.
|
|
37
41
|
|
|
38
42
|
### 3. Simplifies DevOps and CI/CD Pipelines
|
|
39
|
-
|
|
40
|
-
-
|
|
43
|
+
|
|
44
|
+
- Since components are isolated, **testing and deployments** are simplified.
|
|
45
|
+
- You can **avoid Drupal-specific configuration** in CI pipelines, leading to more efficient and maintainable workflows.
|
|
41
46
|
|
|
42
47
|
### 4. Scalability and Flexibility with Faker.js and JSON Schema
|
|
43
|
-
|
|
44
|
-
|
|
48
|
+
|
|
49
|
+
- Tools like **Faker.js** let you generate test data for components without needing real content.
|
|
50
|
+
- **JSON Schema** defines component data clearly and consistently, helping maintain data integrity.
|
|
45
51
|
|
|
46
52
|
### 5. Industry-Standard Tool for Frontend Development
|
|
47
|
-
|
|
48
|
-
|
|
53
|
+
|
|
54
|
+
- **Storybook is widely adopted** in frontend development, which makes onboarding easier, even for developers unfamiliar with Drupal.
|
|
55
|
+
- JSON Schema enables work on components without deep Drupal knowledge, opening the project to a wider developer base.
|
|
49
56
|
|
|
50
57
|
### 6. Drupal-Specific Behavior Embedded in Components
|
|
51
|
-
|
|
52
|
-
|
|
58
|
+
|
|
59
|
+
- Embed **Drupal behaviors** (like `Drupal.attachBehaviors()`) directly into Storybook previews, ensuring consistent component behavior between Storybook and production.
|
|
60
|
+
- Supports `drupalSettings` and `once.js`, so components in Storybook behave identically to their Drupal counterparts.
|
|
53
61
|
|
|
54
62
|
### 7. Twig.js vs Drupal Twig
|
|
63
|
+
|
|
55
64
|
While using Drupal to render components offers tighter integration, there are strong reasons to continue using Twig.js in many scenarios:
|
|
56
65
|
|
|
57
|
-
- Many Components
|
|
66
|
+
- Many Components **Don’t Need Full Drupal Logic**. Basic components (buttons, cards, lists) rely on simple HTML and CSS, not on complex template logic. For such components, Twig.js provides sufficient rendering without the need for full Drupal preprocessing.
|
|
58
67
|
- Twig.js Works Well for Frontend-Focused Use Cases.
|
|
59
68
|
- Styling and Behavior Mismatches Can Be Managed Separately in Drupal implelentation phase.
|
|
60
69
|
|
|
61
70
|
## Features of the Addon
|
|
71
|
+
|
|
62
72
|
- Vite plugin for loading YAML-based SDC configurations.
|
|
63
73
|
- Dynamic path resolution based on namespaces for easy component discovery.
|
|
64
74
|
- Story generator that creates stories directly from YAML files.
|
|
65
75
|
- JSON schema-based props and support for Drupal behaviors.
|
|
66
76
|
|
|
67
77
|
## Dependencies
|
|
78
|
+
|
|
68
79
|
- [vite-plugin-twig-drupal](https://github.com/larowlan/vite-plugin-twig-drupal): Loads Twig with Drupal functions.
|
|
69
80
|
- [json-schema-faker](https://github.com/json-schema-faker/json-schema-faker): Generates mock data for missing props and slots.
|
|
70
81
|
|
|
71
82
|
## Quickstart Guide
|
|
72
83
|
|
|
73
84
|
1. **In theme or module or just empty directory (If package.json not yet exists)**:
|
|
85
|
+
|
|
74
86
|
```bash
|
|
75
87
|
npm init
|
|
76
88
|
echo "node_modules/" >> .gitignore
|
|
77
89
|
```
|
|
78
90
|
|
|
79
91
|
2. **Install dependencies**:
|
|
92
|
+
|
|
80
93
|
```bash
|
|
81
94
|
npm i vite twig storybook-addon-sdc --save-dev
|
|
82
95
|
```
|
|
83
96
|
|
|
84
97
|
3. **Initialize Storybook**:
|
|
98
|
+
|
|
85
99
|
```bash
|
|
86
100
|
npx storybook@latest init --builder vite --type html --no-dev
|
|
87
101
|
```
|
|
88
102
|
|
|
89
103
|
4. **Remove default storybook boilerplate stories (Optional)**:
|
|
104
|
+
|
|
90
105
|
```bash
|
|
91
106
|
rm -rf ./stories
|
|
92
107
|
```
|
|
@@ -105,39 +120,41 @@ While using Drupal to render components offers tighter integration, there are st
|
|
|
105
120
|
To configure the addon, update `.storybook/main.js` as shown below:
|
|
106
121
|
|
|
107
122
|
```js
|
|
108
|
-
import { join } from
|
|
123
|
+
import { join } from 'node:path' // 1. Add path dependency.
|
|
109
124
|
|
|
110
125
|
const config = {
|
|
111
|
-
stories: [
|
|
126
|
+
stories: ['../components/**/*.component.yml'], // 2. Set components glob.
|
|
112
127
|
addons: [
|
|
113
128
|
{
|
|
114
|
-
name:
|
|
129
|
+
name: 'storybook-addon-sdc', // 3. Configure addon.
|
|
115
130
|
options: {
|
|
116
131
|
sdcStorybookOptions: {
|
|
117
|
-
namespace:
|
|
132
|
+
namespace: 'umami', // Your namespace.
|
|
118
133
|
},
|
|
119
|
-
vitePluginTwigDrupalOptions: {
|
|
134
|
+
vitePluginTwigDrupalOptions: {
|
|
135
|
+
// vite-plugin-twig-drupal options.
|
|
120
136
|
namespaces: {
|
|
121
|
-
umami: join(__dirname,
|
|
122
|
-
}
|
|
137
|
+
umami: join(__dirname, '/components'), // Your namespace and path to components.
|
|
138
|
+
},
|
|
123
139
|
},
|
|
124
140
|
jsonSchemaFakerOptions: {}, // json-schema-faker options.
|
|
125
|
-
}
|
|
141
|
+
},
|
|
126
142
|
},
|
|
127
143
|
// Any other addons.
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
144
|
+
'@storybook/addon-essentials',
|
|
145
|
+
'@chromatic-com/storybook',
|
|
146
|
+
'@storybook/addon-interactions',
|
|
131
147
|
],
|
|
132
148
|
framework: {
|
|
133
|
-
name:
|
|
149
|
+
name: '@storybook/html-vite',
|
|
134
150
|
options: {},
|
|
135
151
|
},
|
|
136
|
-
}
|
|
137
|
-
export default config
|
|
152
|
+
}
|
|
153
|
+
export default config
|
|
138
154
|
```
|
|
139
155
|
|
|
140
156
|
## Setting Default Values
|
|
157
|
+
|
|
141
158
|
For `json-schema-faker` to generate reliable data, use `default` or `examples` in your SDC schema:
|
|
142
159
|
|
|
143
160
|
```yaml
|
|
@@ -158,10 +175,12 @@ slots:
|
|
|
158
175
|
```
|
|
159
176
|
|
|
160
177
|
Refer to:
|
|
178
|
+
|
|
161
179
|
- [Drupal SDC Documentation](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/annotated-example-componentyml)
|
|
162
180
|
- [JSON Schema Documentation](https://json-schema.org/understanding-json-schema/reference/annotations)
|
|
163
181
|
|
|
164
182
|
## Creating Experimental Stories
|
|
183
|
+
|
|
165
184
|
By default, the addon generates only a basic story for each component. To add more stories, use `thirdPartySettings` in the SDC YAML file:
|
|
166
185
|
|
|
167
186
|
```yaml
|
|
@@ -171,21 +190,21 @@ thirdPartySettings:
|
|
|
171
190
|
preview:
|
|
172
191
|
title: Preview
|
|
173
192
|
props:
|
|
174
|
-
html_tag:
|
|
193
|
+
html_tag: 'div'
|
|
175
194
|
slots:
|
|
176
195
|
content:
|
|
177
196
|
- type: component
|
|
178
|
-
component:
|
|
197
|
+
component: 'umami:title'
|
|
179
198
|
props:
|
|
180
199
|
label: test
|
|
181
200
|
preview2:
|
|
182
201
|
title: Preview2
|
|
183
202
|
props:
|
|
184
|
-
html_tag:
|
|
203
|
+
html_tag: 'div'
|
|
185
204
|
slots:
|
|
186
205
|
content:
|
|
187
206
|
- type: component
|
|
188
|
-
component:
|
|
207
|
+
component: 'umami:title'
|
|
189
208
|
props:
|
|
190
209
|
label: test2
|
|
191
210
|
```
|
|
@@ -194,8 +213,8 @@ thirdPartySettings:
|
|
|
194
213
|
|
|
195
214
|
The [community will have to decide](https://docs.google.com/document/d/1wCQLXrK1lrV2gYlqmqD2pybTql6_H1dByWIKB5xQFcQ/edit?tab=t.0#heading=h.3949vjfiqczr) what format the YAML stories should be.
|
|
196
215
|
|
|
197
|
-
|
|
198
216
|
## Regular storybook
|
|
217
|
+
|
|
199
218
|
All storybook functions work as usual and you can import SDC YAML into `.stories.js`
|
|
200
219
|
|
|
201
220
|
[example](https://github.com/iberdinsky-skilld/sdc-addon/blob/main/stories/page-example.stories.js)
|
|
@@ -225,14 +244,15 @@ export const Basic = {}
|
|
|
225
244
|
```
|
|
226
245
|
|
|
227
246
|
## Storybook Example Live
|
|
228
|
-
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.
|
|
229
247
|
|
|
248
|
+
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.
|
|
230
249
|
|
|
231
250
|
## Known Issues
|
|
251
|
+
|
|
232
252
|
- `$ref: json-schema-definitions://` for SDC from Experience Builder is unsupported.
|
|
233
253
|
- The addon relies on [Experimental indexers](https://storybook.js.org/docs/api/main-config/main-config-indexers).
|
|
234
254
|
|
|
235
255
|
## UI Patterns
|
|
256
|
+
|
|
236
257
|
- Variants are not yet supported ([Issue 3390712](https://www.drupal.org/project/drupal/issues/3390712)).
|
|
237
258
|
- Custom Twig filters and functions are not supported ([UI Patterns TwigExtension](https://git.drupalcode.org/project/ui_patterns/-/blob/8.x-1.x/src/Template/TwigExtension.php)).
|
|
238
|
-
|
package/dist/preset.js
CHANGED
|
@@ -5537,7 +5537,8 @@ var argTypesGenerator_default = (content) => {
|
|
|
5537
5537
|
// src/storiesGenerator.ts
|
|
5538
5538
|
init_esm_shims();
|
|
5539
5539
|
var storiesGenerator_default = (stories) => {
|
|
5540
|
-
return Object.entries(stories).map(
|
|
5540
|
+
return Object.entries(stories).map(
|
|
5541
|
+
([storyKey, { props = {}, slots = {} }]) => `
|
|
5541
5542
|
export const ${storyKey} = {
|
|
5542
5543
|
args: {
|
|
5543
5544
|
...Basic.args,
|
|
@@ -5548,7 +5549,8 @@ var storiesGenerator_default = (stories) => {
|
|
|
5548
5549
|
Drupal.attachBehaviors(canvasElement, window.drupalSettings);
|
|
5549
5550
|
},
|
|
5550
5551
|
};
|
|
5551
|
-
`
|
|
5552
|
+
`
|
|
5553
|
+
).join("\n");
|
|
5552
5554
|
};
|
|
5553
5555
|
var generateArgs2 = (args, isSlot = false) => {
|
|
5554
5556
|
return Object.entries(args).map(([key, value]) => {
|
|
@@ -5723,22 +5725,15 @@ var yamlStoriesIndexer = {
|
|
|
5723
5725
|
// src/preset.ts
|
|
5724
5726
|
import twig from "vite-plugin-twig-drupal";
|
|
5725
5727
|
import { mergeConfig } from "vite";
|
|
5726
|
-
import { resolve as resolve3
|
|
5727
|
-
import
|
|
5728
|
-
|
|
5729
|
-
return fs.readdirSync(baseDir, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => join2(baseDir, dirent.name));
|
|
5730
|
-
};
|
|
5731
|
-
var getComponentDirectories = () => {
|
|
5732
|
-
const baseComponentDir = resolve3("./components");
|
|
5733
|
-
const subdirectories = getSubdirectories2(baseComponentDir);
|
|
5734
|
-
return [baseComponentDir, ...subdirectories];
|
|
5735
|
-
};
|
|
5728
|
+
import { resolve as resolve3 } from "path";
|
|
5729
|
+
import { existsSync as existsSync2 } from "fs";
|
|
5730
|
+
import glob from "glob";
|
|
5736
5731
|
var resolveComponentPath2 = (namespace, component) => {
|
|
5737
|
-
const componentDirectories =
|
|
5732
|
+
const componentDirectories = glob.sync("./components/**/*.component.yml");
|
|
5738
5733
|
const possiblePaths = componentDirectories.map(
|
|
5739
5734
|
(dir) => resolve3(`${dir}/${component}/${component}.component.yml`)
|
|
5740
5735
|
);
|
|
5741
|
-
return possiblePaths.find((path2) =>
|
|
5736
|
+
return possiblePaths.find((path2) => existsSync2(path2));
|
|
5742
5737
|
};
|
|
5743
5738
|
function viteFinal(config, options) {
|
|
5744
5739
|
const { namespace } = options.sdcStorybookOptions;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "storybook-addon-sdc",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"description": "Drupal Single Directory Components as stories",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"SDC",
|
|
@@ -32,19 +32,21 @@
|
|
|
32
32
|
"prerelease": "zx scripts/prepublish-checks.js",
|
|
33
33
|
"release": "npm run build && auto shipit",
|
|
34
34
|
"storybook": "storybook dev -p 6006",
|
|
35
|
-
"build-storybook": "storybook build"
|
|
35
|
+
"build-storybook": "storybook build",
|
|
36
|
+
"format": "prettier --write ."
|
|
36
37
|
},
|
|
37
38
|
"dependencies": {
|
|
39
|
+
"glob": "^11.0.0",
|
|
38
40
|
"json-schema-faker": "^0.5.8",
|
|
39
41
|
"vite-plugin-twig-drupal": "^1.4.2"
|
|
40
42
|
},
|
|
41
43
|
"devDependencies": {
|
|
42
|
-
"@storybook/addon-essentials": "^8.4.
|
|
43
|
-
"@storybook/addon-interactions": "^8.4.
|
|
44
|
-
"@storybook/addon-links": "^8.4.
|
|
45
|
-
"@storybook/html-vite": "^8.4.
|
|
46
|
-
"@storybook/test": "^8.4.
|
|
47
|
-
"@storybook/types": "^8.4.
|
|
44
|
+
"@storybook/addon-essentials": "^8.4.4",
|
|
45
|
+
"@storybook/addon-interactions": "^8.4.4",
|
|
46
|
+
"@storybook/addon-links": "^8.4.4",
|
|
47
|
+
"@storybook/html-vite": "^8.4.4",
|
|
48
|
+
"@storybook/test": "^8.4.4",
|
|
49
|
+
"@storybook/types": "^8.4.4",
|
|
48
50
|
"@types/json-schema": "^7.0.15",
|
|
49
51
|
"@types/node": "^22.8.7",
|
|
50
52
|
"auto": "^11.3.0",
|
|
@@ -54,7 +56,7 @@
|
|
|
54
56
|
"prompts": "^2.4.2",
|
|
55
57
|
"react": "^18.2.0",
|
|
56
58
|
"react-dom": "^18.2.0",
|
|
57
|
-
"storybook": "^8.4.
|
|
59
|
+
"storybook": "^8.4.4",
|
|
58
60
|
"tsup": "^8.2.4",
|
|
59
61
|
"typescript": "^5.5.4",
|
|
60
62
|
"vite": "^5.3.5",
|