storybook-addon-sdc 0.1.23 → 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.
Files changed (3) hide show
  1. package/README.md +54 -34
  2. package/dist/preset.js +9 -14
  3. 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
  [![Demo GIF](https://i.gyazo.com/2dcfa650c961679430d45eef24a82ab8.gif)](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
- - Following the __BEM (Block Element Modifier)__ methodology, a component should work independently across environments.
32
- - 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
+
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
- - No need to install or configure Drupal dependencies for component development.
36
- - Work faster by developing frontend components in Storybook without running a heavy Drupal instance.
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
- - Since components are isolated, __testing and deployments__ are simplified.
40
- - You can __avoid Drupal-specific configuration__ in CI pipelines, leading to more efficient and maintainable workflows.
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
- - Tools like **Faker.js** let you generate test data for components without needing real content.
44
- - **JSON Schema** defines component data clearly and consistently, helping maintain data integrity.
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
- - **Storybook is widely adopted** in frontend development, which makes onboarding easier, even for developers unfamiliar with Drupal.
48
- - JSON Schema enables work on components without deep Drupal knowledge, opening the project to a wider developer base.
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
- - Embed **Drupal behaviors** (like `Drupal.attachBehaviors()`) directly into Storybook previews, ensuring consistent component behavior between Storybook and production.
52
- - Supports `drupalSettings` and `once.js`, so components in Storybook behave identically to their Drupal counterparts.
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 __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.
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 "node:path"; // 1. Add path dependency.
123
+ import { join } from 'node:path' // 1. Add path dependency.
109
124
 
110
125
  const config = {
111
- stories: ["../components/**/*.component.yml"], // 2. Set components glob.
126
+ stories: ['../components/**/*.component.yml'], // 2. Set components glob.
112
127
  addons: [
113
128
  {
114
- name: "storybook-addon-sdc", // 3. Configure addon.
129
+ name: 'storybook-addon-sdc', // 3. Configure addon.
115
130
  options: {
116
131
  sdcStorybookOptions: {
117
- namespace: "umami", // Your namespace.
132
+ namespace: 'umami', // Your namespace.
118
133
  },
119
- vitePluginTwigDrupalOptions: { // vite-plugin-twig-drupal options.
134
+ vitePluginTwigDrupalOptions: {
135
+ // vite-plugin-twig-drupal options.
120
136
  namespaces: {
121
- umami: join(__dirname, "/components") // Your namespace and path to components.
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
- "@storybook/addon-essentials",
129
- "@chromatic-com/storybook",
130
- "@storybook/addon-interactions",
144
+ '@storybook/addon-essentials',
145
+ '@chromatic-com/storybook',
146
+ '@storybook/addon-interactions',
131
147
  ],
132
148
  framework: {
133
- name: "@storybook/html-vite",
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: "div"
193
+ html_tag: 'div'
175
194
  slots:
176
195
  content:
177
196
  - type: component
178
- component: "umami:title"
197
+ component: 'umami:title'
179
198
  props:
180
199
  label: test
181
200
  preview2:
182
201
  title: Preview2
183
202
  props:
184
- html_tag: "div"
203
+ html_tag: 'div'
185
204
  slots:
186
205
  content:
187
206
  - type: component
188
- component: "umami:title"
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(([storyKey, { props = {}, slots = {} }]) => `
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
- `).join("\n");
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, join as join2 } from "path";
5727
- import fs from "fs";
5728
- var getSubdirectories2 = (baseDir) => {
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 = getComponentDirectories();
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) => fs.existsSync(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.1.23",
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.2",
43
- "@storybook/addon-interactions": "^8.4.2",
44
- "@storybook/addon-links": "^8.4.2",
45
- "@storybook/html-vite": "^8.4.2",
46
- "@storybook/test": "^8.4.2",
47
- "@storybook/types": "^8.4.2",
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.2",
59
+ "storybook": "^8.4.4",
58
60
  "tsup": "^8.2.4",
59
61
  "typescript": "^5.5.4",
60
62
  "vite": "^5.3.5",