storybook-addon-sdc 0.9.5 → 0.9.7
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 +208 -188
- package/dist/preset.js +3 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,14 +9,14 @@ This addon streamlines the integration of Drupal Single Directory Components (SD
|
|
|
9
9
|
- [Overview](#overview)
|
|
10
10
|
- [Storybook Example Live](#storybook-example-live)
|
|
11
11
|
- [Features of the Addon](#features-of-the-addon)
|
|
12
|
-
- [Why Choose SDC Storybook Over Alternatives?](#why-choose-sdc-storybook-over-alternatives)
|
|
13
12
|
- [Quickstart Guide](#quickstart-guide)
|
|
14
13
|
- [Configuration](#configuration)
|
|
15
|
-
- [Setting Default Values](#setting-default-values)
|
|
16
14
|
- [Creating Experimental Stories](#creating-experimental-stories)
|
|
17
15
|
- [Support for Single Story Files (\*.story.yml)](#support-for-single-story-files-storyyml)
|
|
18
16
|
- [Regular Storybook](#regular-storybook)
|
|
19
17
|
- [Configuration Options](#configuration-options)
|
|
18
|
+
- [Setting Default Values](#setting-default-values)
|
|
19
|
+
- [Why Choose SDC Storybook Over Alternatives?](#why-choose-sdc-storybook-over-alternatives)
|
|
20
20
|
- [Dependencies](#dependencies)
|
|
21
21
|
- [Known Issues](#known-issues)
|
|
22
22
|
- [UI Patterns](#ui-patterns)
|
|
@@ -43,49 +43,7 @@ The SDC Storybook Addon simplifies the integration of Drupal Single Directory Co
|
|
|
43
43
|
- **JSON Schema Support**: Supports JSON Schema for props and slots, enabling the generation of mock data for missing values and ensuring data consistency.
|
|
44
44
|
- **Drupal Behavior Embedding**: Allows you to directly embed Drupal behaviors like `Drupal.attachBehaviors()` into Storybook previews, ensuring components behave similarly to their Drupal counterparts.
|
|
45
45
|
- **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).
|
|
46
|
-
|
|
47
|
-
## Why Choose SDC Storybook Over Alternatives?
|
|
48
|
-
|
|
49
|
-
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:
|
|
50
|
-
|
|
51
|
-
### 1. Component Independence and Modularity
|
|
52
|
-
|
|
53
|
-
- Following the **BEM (Block Element Modifier)** methodology, a component should work independently across environments.
|
|
54
|
-
- The functionality of your component must not depend on the **Drupal version**, or the active **Drupal theme** — it should be portable to **any** system.
|
|
55
|
-
|
|
56
|
-
### 2. No Complex Drupal Setup Required
|
|
57
|
-
|
|
58
|
-
- No need to install or configure Drupal dependencies for component development.
|
|
59
|
-
- Work faster by developing frontend components in Storybook without running a heavy Drupal instance.
|
|
60
|
-
|
|
61
|
-
### 3. Simplifies DevOps and CI/CD Pipelines
|
|
62
|
-
|
|
63
|
-
- Since components are isolated, **testing and deployments** are simplified.
|
|
64
|
-
- You can **avoid Drupal-specific configuration** in CI pipelines, leading to more efficient and maintainable workflows.
|
|
65
|
-
|
|
66
|
-
### 4. Scalability and Flexibility with Faker.js and JSON Schema
|
|
67
|
-
|
|
68
|
-
- Tools like **Faker.js** let you generate test data for components without needing real content.
|
|
69
|
-
- **JSON Schema** defines component data clearly and consistently, helping maintain data integrity.
|
|
70
|
-
|
|
71
|
-
### 5. Industry-Standard Tool for Frontend Development
|
|
72
|
-
|
|
73
|
-
- **Storybook is widely adopted** in frontend development, which makes onboarding easier, even for developers unfamiliar with Drupal.
|
|
74
|
-
- JSON Schema enables work on components without deep Drupal knowledge, opening the project to a wider developer base.
|
|
75
|
-
|
|
76
|
-
### 6. Drupal-Specific Behavior Embedded in Components
|
|
77
|
-
|
|
78
|
-
- Embed **Drupal behaviors** (like `Drupal.attachBehaviors()`) directly into Storybook previews, ensuring consistent component behavior between Storybook and production.
|
|
79
|
-
- Supports `drupalSettings` and `once.js`, so components in Storybook behave identically to their Drupal counterparts.
|
|
80
|
-
|
|
81
|
-
### 7. Twig.js, Twing, and Drupal Twig
|
|
82
|
-
|
|
83
|
-
While using Drupal to render components offers tighter integration, there are strong reasons to use Twig.js or Twing in many scenarios:
|
|
84
|
-
|
|
85
|
-
- 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 or Twing provide sufficient rendering without the need for full Drupal preprocessing.
|
|
86
|
-
- **Twig.js** works well for most frontend-focused use cases.
|
|
87
|
-
- **Twing** is a modern, actively maintained Twig implementation for Node.js that offers better compatibility with Drupal's Twig features and syntax.
|
|
88
|
-
- Styling and behavior mismatches can be managed separately in the Drupal implementation phase.
|
|
46
|
+
- **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.
|
|
89
47
|
|
|
90
48
|
## Quickstart Guide
|
|
91
49
|
|
|
@@ -134,9 +92,7 @@ While using Drupal to render components offers tighter integration, there are st
|
|
|
134
92
|
## Configuration
|
|
135
93
|
|
|
136
94
|
To configure the addon, update `.storybook/main.js` as shown below:
|
|
137
|
-
You can use this plugin either with [Twig.js](https://github.com/twigjs/twig.js) or [Twing.js](https://twing.nightlycommit.com/).
|
|
138
|
-
|
|
139
|
-
#### [Twig.js](https://github.com/twigjs/twig.js)
|
|
95
|
+
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. Only one of vitePluginTwigDrupalOptions or vitePluginTwingDrupalOptions should be active, depending on your twigLib setting.
|
|
140
96
|
|
|
141
97
|
```js
|
|
142
98
|
import { join } from 'node:path' // 1. Add dependencies.
|
|
@@ -149,51 +105,24 @@ const config = {
|
|
|
149
105
|
name: 'storybook-addon-sdc', // 3. Configure addon.
|
|
150
106
|
options: {
|
|
151
107
|
sdcStorybookOptions: {
|
|
108
|
+
twigLib: 'twig', // 'twig' for Twig.js or 'twing' for Twing.
|
|
152
109
|
namespace: 'umami', // Your namespace.
|
|
153
110
|
},
|
|
111
|
+
|
|
112
|
+
// vite-plugin-twig-drupal options. Comment if using Twing.
|
|
154
113
|
vitePluginTwigDrupalOptions: {
|
|
155
|
-
// vite-plugin-twig-drupal options.
|
|
156
114
|
namespaces: {
|
|
157
115
|
umami: join(cwd(), './components'), // Your namespace and path to components.
|
|
158
116
|
},
|
|
159
117
|
},
|
|
160
|
-
jsonSchemaFakerOptions: {}, // json-schema-faker options.
|
|
161
|
-
},
|
|
162
|
-
},
|
|
163
|
-
// Any other addons.
|
|
164
|
-
'@chromatic-com/storybook',
|
|
165
|
-
],
|
|
166
|
-
framework: {
|
|
167
|
-
name: '@storybook/html-vite',
|
|
168
|
-
options: {},
|
|
169
|
-
},
|
|
170
|
-
}
|
|
171
|
-
export default config
|
|
172
|
-
```
|
|
173
118
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
119
|
+
// vite-plugin-twing-drupal options. Uncomment if using Twing.
|
|
120
|
+
// vitePluginTwingDrupalOptions: {
|
|
121
|
+
// namespaces: {
|
|
122
|
+
// umami: [join(cwd(), './components')],
|
|
123
|
+
// },
|
|
124
|
+
// },
|
|
179
125
|
|
|
180
|
-
const config = {
|
|
181
|
-
stories: ['../components/**/*.component.yml'], // 2. Set components glob.
|
|
182
|
-
addons: [
|
|
183
|
-
{
|
|
184
|
-
name: 'storybook-addon-sdc', // 3. Configure addon.
|
|
185
|
-
options: {
|
|
186
|
-
sdcStorybookOptions: {
|
|
187
|
-
twigLib: 'twing',
|
|
188
|
-
namespace: 'umami', // Your namespace.
|
|
189
|
-
},
|
|
190
|
-
vitePluginTwingDrupalOptions: {
|
|
191
|
-
namespaces: {
|
|
192
|
-
umami: [join(cwd(), './components')],
|
|
193
|
-
},
|
|
194
|
-
// (Optional) With twing hooks you can adjust twing environment.
|
|
195
|
-
hooks: join(cwd(), '.storybook/twing-hooks.js'),
|
|
196
|
-
},
|
|
197
126
|
jsonSchemaFakerOptions: {}, // json-schema-faker options.
|
|
198
127
|
},
|
|
199
128
|
},
|
|
@@ -208,50 +137,6 @@ const config = {
|
|
|
208
137
|
export default config
|
|
209
138
|
```
|
|
210
139
|
|
|
211
|
-
Sample twing hook file. See [twing.js documentation](https://twing.nightlycommit.com/) for more infos.
|
|
212
|
-
|
|
213
|
-
```js
|
|
214
|
-
import { createSynchronousFunction } from 'twing'
|
|
215
|
-
|
|
216
|
-
/**
|
|
217
|
-
* Simple test function.
|
|
218
|
-
*/
|
|
219
|
-
function testFunction() {
|
|
220
|
-
return 'IT WORKS!'
|
|
221
|
-
}
|
|
222
|
-
|
|
223
|
-
export function initEnvironment(twingEnvironment, config = {}) {
|
|
224
|
-
const func = createSynchronousFunction('testFunction', testFunction, [])
|
|
225
|
-
twingEnvironment.addFunction(func)
|
|
226
|
-
}
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
## Setting Default Values
|
|
230
|
-
|
|
231
|
-
For `json-schema-faker` to generate reliable data, use `default` or `examples` in your SDC schema:
|
|
232
|
-
|
|
233
|
-
```yaml
|
|
234
|
-
props:
|
|
235
|
-
type: object
|
|
236
|
-
properties:
|
|
237
|
-
html_tag:
|
|
238
|
-
type: string
|
|
239
|
-
enum:
|
|
240
|
-
- article
|
|
241
|
-
- div
|
|
242
|
-
default: article
|
|
243
|
-
slots:
|
|
244
|
-
content:
|
|
245
|
-
title: Content
|
|
246
|
-
examples:
|
|
247
|
-
- Hello! I'm card content
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
Refer to:
|
|
251
|
-
|
|
252
|
-
- [Drupal SDC Documentation](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/annotated-example-componentyml)
|
|
253
|
-
- [JSON Schema Documentation](https://json-schema.org/understanding-json-schema/reference/annotations)
|
|
254
|
-
|
|
255
140
|
## Creating Experimental Stories
|
|
256
141
|
|
|
257
142
|
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:
|
|
@@ -302,50 +187,87 @@ The addon dynamically renders the components and stories as defined:
|
|
|
302
187
|
|
|
303
188
|
[](https://gyazo.com/7212a3f44052ebde34b59a1555d96afe)
|
|
304
189
|
|
|
305
|
-
|
|
190
|
+
## Core and custom story node types
|
|
306
191
|
|
|
307
|
-
|
|
192
|
+
Plugin supports 3 core story node types: `component`, `element`, and `image`.
|
|
308
193
|
|
|
309
194
|
Use `component` to nest other components within your story.
|
|
310
195
|
|
|
311
196
|
```yaml
|
|
312
197
|
type: component
|
|
313
198
|
component: 'umami:badge'
|
|
314
|
-
props:
|
|
315
|
-
icon: serves
|
|
316
|
-
slots:
|
|
317
|
-
text:
|
|
318
|
-
type: component
|
|
319
|
-
component: 'umami:title'
|
|
320
199
|
```
|
|
321
200
|
|
|
322
|
-
|
|
201
|
+
Use `element` to embed HTML markup within a specific tag.
|
|
323
202
|
|
|
324
|
-
|
|
203
|
+
```yaml
|
|
204
|
+
type: element
|
|
205
|
+
value: 'Hello World!'
|
|
206
|
+
attributes:
|
|
207
|
+
class: custom-class
|
|
208
|
+
```
|
|
325
209
|
|
|
326
|
-
Use `
|
|
210
|
+
Use `image` to embed images into your story.
|
|
327
211
|
|
|
328
212
|
```yaml
|
|
329
|
-
type:
|
|
330
|
-
|
|
213
|
+
type: image
|
|
214
|
+
uri: https://placehold.co/1200x400
|
|
331
215
|
attributes:
|
|
332
|
-
class: class
|
|
216
|
+
class: custom-class
|
|
333
217
|
```
|
|
334
218
|
|
|
335
|
-
|
|
219
|
+
Example of using `element` and `image` in a story:
|
|
336
220
|
|
|
337
|
-
|
|
221
|
+
```yaml
|
|
222
|
+
thirdPartySettings:
|
|
223
|
+
sdcStorybook:
|
|
224
|
+
stories:
|
|
225
|
+
preview:
|
|
226
|
+
slots:
|
|
227
|
+
content:
|
|
228
|
+
# Result:
|
|
229
|
+
# <h2 class="custom-class"><span>Hello</span></h2>
|
|
230
|
+
- type: element
|
|
231
|
+
tag: 'h2'
|
|
232
|
+
value: '<span>Hello</span>'
|
|
233
|
+
attributes:
|
|
234
|
+
class: 'custom-class'
|
|
235
|
+
|
|
236
|
+
# Result:
|
|
237
|
+
# <img class="custom-class" src="https://placehold.co/600x400" />
|
|
238
|
+
- type: image
|
|
239
|
+
uri: 'https://placehold.co/600x400'
|
|
240
|
+
attributes:
|
|
241
|
+
class: 'custom-class'
|
|
242
|
+
```
|
|
338
243
|
|
|
339
|
-
|
|
244
|
+
### You can add custom renderers for additional `story` node types.
|
|
245
|
+
|
|
246
|
+
For example, to render a custom `icon` type:
|
|
340
247
|
|
|
341
248
|
```yaml
|
|
342
|
-
type:
|
|
343
|
-
|
|
344
|
-
attributes:
|
|
345
|
-
class: class-1
|
|
249
|
+
- type: icon
|
|
250
|
+
icon: arrow
|
|
346
251
|
```
|
|
347
252
|
|
|
348
|
-
|
|
253
|
+
Add the following to your `sdcStorybookOptions`:
|
|
254
|
+
|
|
255
|
+
```js
|
|
256
|
+
sdcStorybookOptions: {
|
|
257
|
+
...
|
|
258
|
+
storyNodesRenderer: [
|
|
259
|
+
{
|
|
260
|
+
appliesTo: item => item?.type === 'icon',
|
|
261
|
+
render: item =>
|
|
262
|
+
JSON.stringify(
|
|
263
|
+
`<svg class="icon" aria-hidden="true"><use xlink:href="#${item.icon}"></use></svg>`
|
|
264
|
+
),
|
|
265
|
+
priority: -4,
|
|
266
|
+
},
|
|
267
|
+
],
|
|
268
|
+
...
|
|
269
|
+
}
|
|
270
|
+
```
|
|
349
271
|
|
|
350
272
|
## Support for Single Story Files (`*.story.yml`)
|
|
351
273
|
|
|
@@ -358,17 +280,14 @@ This means you can create independent stories for your components by simply addi
|
|
|
358
280
|
```yaml
|
|
359
281
|
# components/slider/slider.badges.story.yml
|
|
360
282
|
name: Badges
|
|
361
|
-
|
|
283
|
+
slots:
|
|
362
284
|
slides:
|
|
363
285
|
- type: component
|
|
364
286
|
component: 'umami:badge'
|
|
365
287
|
props:
|
|
366
288
|
icon: timer
|
|
367
289
|
slots:
|
|
368
|
-
text:
|
|
369
|
-
type: html_tag
|
|
370
|
-
tag: span
|
|
371
|
-
value: Test
|
|
290
|
+
text: Hello
|
|
372
291
|
- type: component
|
|
373
292
|
component: 'umami:badge'
|
|
374
293
|
props:
|
|
@@ -383,42 +302,13 @@ props:
|
|
|
383
302
|
text: Ciao
|
|
384
303
|
```
|
|
385
304
|
|
|
386
|
-
## Extending SDC Story Rendering
|
|
387
|
-
|
|
388
|
-
You can add custom renderers for additional `story` node types.
|
|
389
|
-
For example, to render a custom `icon` type:
|
|
390
|
-
|
|
391
|
-
```yaml
|
|
392
|
-
- type: icon
|
|
393
|
-
icon: arrow
|
|
394
|
-
```
|
|
395
|
-
|
|
396
|
-
Add the following to your `sdcStorybookOptions`:
|
|
397
|
-
|
|
398
|
-
```ts
|
|
399
|
-
const sdcStorybookOptions: SDCStorybookOptions = {
|
|
400
|
-
...
|
|
401
|
-
storyNodesRenderer: [
|
|
402
|
-
{
|
|
403
|
-
appliesTo: item => item?.type === 'icon',
|
|
404
|
-
render: item =>
|
|
405
|
-
Json.toString(
|
|
406
|
-
`<svg class="icon" aria-hidden="true"><use xlink:href="#${item.icon}"></use></svg>`
|
|
407
|
-
),
|
|
408
|
-
priority: -4,
|
|
409
|
-
},
|
|
410
|
-
],
|
|
411
|
-
...
|
|
412
|
-
}
|
|
413
|
-
```
|
|
414
|
-
|
|
415
305
|
### Why stories experimental?
|
|
416
306
|
|
|
417
307
|
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.
|
|
418
308
|
|
|
419
309
|
## Regular storybook
|
|
420
310
|
|
|
421
|
-
All
|
|
311
|
+
All Storybook functions work as usual, and you can import SDC YAML into `.stories.js` files.
|
|
422
312
|
|
|
423
313
|
[example](https://github.com/iberdinsky-skilld/sdc-addon/blob/main/stories/page-example.stories.js)
|
|
424
314
|
|
|
@@ -448,7 +338,68 @@ export const Basic = {}
|
|
|
448
338
|
|
|
449
339
|
## Configuration Options
|
|
450
340
|
|
|
451
|
-
|
|
341
|
+
- **vitePluginTwigDrupalOptions**: Options for [vite-plugin-twig-drupal](https://github.com/larowlan/vite-plugin-twig-drupal) (Twig.js). Use when `twigLib` is set to `'twig'`.
|
|
342
|
+
- **vitePluginTwingDrupalOptions**: Options for [vite-plugin-twing-drupal](https://github.com/christianwiedemann/vite-plugin-twing-drupal) (Twing). Use when `twigLib` is set to `'twing'`.
|
|
343
|
+
- **customDefs**: An object with custom JSON schema definitions for your components.
|
|
344
|
+
- **externalDefs**: An array of URLs or local file paths to external schema definition files.
|
|
345
|
+
- **validate**: A URL or path to a JSON schema for validating your SDC components.
|
|
346
|
+
|
|
347
|
+
### Twig.js with `vitePluginTwigDrupalOptions`
|
|
348
|
+
|
|
349
|
+
It is possible to pass options to the underlying `vite-plugin-twig-drupal` plugin. See [vite-plugin-twig-drupal](https://github.com/larowlan/vite-plugin-twig-drupal/blob/main/README.md#installation)
|
|
350
|
+
|
|
351
|
+
```js
|
|
352
|
+
vitePluginTwigDrupalOptions: {
|
|
353
|
+
namespaces: {
|
|
354
|
+
umami: join(cwd(), './components'), // Your namespace and path to components.
|
|
355
|
+
},
|
|
356
|
+
functions: {
|
|
357
|
+
// You can add custom functions - each is a function that is passed the active Twig instance and should call
|
|
358
|
+
// e.g. extendFunction to register a function
|
|
359
|
+
reverse: (twigInstance) => twigInstance.extendFunction("reverse", () => (text) => text.split(' ').reverse().join(' ')),
|
|
360
|
+
// e.g. extendFilter to register a filter
|
|
361
|
+
clean_unique_id: (twigInstance) => twigInstance.extendFilter("clean_unique_id", () => (text) => text.split(' ').reverse().join(' ')),
|
|
362
|
+
},
|
|
363
|
+
globalContext: {
|
|
364
|
+
// Global variables that should be present in all templates.
|
|
365
|
+
active_theme: 'my_super_theme',
|
|
366
|
+
is_front_page: false,
|
|
367
|
+
},
|
|
368
|
+
},
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
### Twing with `vitePluginTwingDrupalOptions`
|
|
372
|
+
|
|
373
|
+
It is possible to pass options to the underlying `vite-plugin-twing-drupal` plugin. See [Twing documentation](https://twing.nightlycommit.com/) for more information.
|
|
374
|
+
|
|
375
|
+
```js
|
|
376
|
+
vitePluginTwingDrupalOptions: {
|
|
377
|
+
namespaces: {
|
|
378
|
+
umami: [join(cwd(), './components')],
|
|
379
|
+
},
|
|
380
|
+
// (Optional) With twing hooks you can adjust twing environment.
|
|
381
|
+
hooks: join(cwd(), '.storybook/twing-hooks.js'),
|
|
382
|
+
},
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
Sample twing hook file.
|
|
386
|
+
|
|
387
|
+
```js
|
|
388
|
+
// .storybook/twing-hooks.js
|
|
389
|
+
import { createSynchronousFunction } from 'twing'
|
|
390
|
+
|
|
391
|
+
/**
|
|
392
|
+
* Simple test function.
|
|
393
|
+
*/
|
|
394
|
+
function testFunction() {
|
|
395
|
+
return 'IT WORKS!'
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
export function initEnvironment(twingEnvironment, config = {}) {
|
|
399
|
+
const func = createSynchronousFunction('testFunction', testFunction, [])
|
|
400
|
+
twingEnvironment.addFunction(func)
|
|
401
|
+
}
|
|
402
|
+
```
|
|
452
403
|
|
|
453
404
|
### `customDefs`
|
|
454
405
|
|
|
@@ -525,11 +476,80 @@ const config = {
|
|
|
525
476
|
}
|
|
526
477
|
```
|
|
527
478
|
|
|
479
|
+
## Setting Default Values
|
|
480
|
+
|
|
481
|
+
For `json-schema-faker` to generate reliable data, use `default` or `examples` in your SDC schema:
|
|
482
|
+
|
|
483
|
+
```yaml
|
|
484
|
+
props:
|
|
485
|
+
type: object
|
|
486
|
+
properties:
|
|
487
|
+
html_tag:
|
|
488
|
+
type: string
|
|
489
|
+
enum:
|
|
490
|
+
- article
|
|
491
|
+
- div
|
|
492
|
+
default: article
|
|
493
|
+
slots:
|
|
494
|
+
content:
|
|
495
|
+
title: Content
|
|
496
|
+
examples:
|
|
497
|
+
- Hello! I'm card content
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
Refer to:
|
|
501
|
+
|
|
502
|
+
- [Drupal SDC Documentation](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/annotated-example-componentyml)
|
|
503
|
+
- [JSON Schema Documentation](https://json-schema.org/understanding-json-schema/reference/annotations)
|
|
504
|
+
|
|
505
|
+
## Why Choose SDC Storybook Over Alternatives?
|
|
506
|
+
|
|
507
|
+
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:
|
|
508
|
+
|
|
509
|
+
### 1. Component Independence and Modularity
|
|
510
|
+
|
|
511
|
+
- Following the **BEM (Block Element Modifier)** methodology, a component should work independently across environments.
|
|
512
|
+
- The functionality of your component must not depend on the **Drupal version**, or the active **Drupal theme** — it should be portable to **any** system.
|
|
513
|
+
|
|
514
|
+
### 2. No Complex Drupal Setup Required
|
|
515
|
+
|
|
516
|
+
- No need to install or configure Drupal dependencies for component development.
|
|
517
|
+
- Work faster by developing frontend components in Storybook without running a heavy Drupal instance.
|
|
518
|
+
|
|
519
|
+
### 3. Simplifies DevOps and CI/CD Pipelines
|
|
520
|
+
|
|
521
|
+
- Since components are isolated, **testing and deployments** are simplified.
|
|
522
|
+
- You can **avoid Drupal-specific configuration** in CI pipelines, leading to more efficient and maintainable workflows.
|
|
523
|
+
|
|
524
|
+
### 4. Scalability and Flexibility with Faker.js and JSON Schema
|
|
525
|
+
|
|
526
|
+
- Tools like **Faker.js** let you generate test data for components without needing real content.
|
|
527
|
+
- **JSON Schema** defines component data clearly and consistently, helping maintain data integrity.
|
|
528
|
+
|
|
529
|
+
### 5. Industry-Standard Tool for Frontend Development
|
|
530
|
+
|
|
531
|
+
- **Storybook is widely adopted** in frontend development, which makes onboarding easier, even for developers unfamiliar with Drupal.
|
|
532
|
+
- JSON Schema enables working on components without deep Drupal knowledge, opening the project to a wider developer base.
|
|
533
|
+
|
|
534
|
+
### 6. Drupal-Specific Behavior Embedded in Components
|
|
535
|
+
|
|
536
|
+
- Embed **Drupal behaviors** (like `Drupal.attachBehaviors()`) directly into Storybook previews, ensuring consistent component behavior between Storybook and production.
|
|
537
|
+
- Supports `drupalSettings` and `once.js`, so components in Storybook behave identically to their Drupal counterparts.
|
|
538
|
+
|
|
539
|
+
### 7. Twig.js, Twing, and Drupal Twig
|
|
540
|
+
|
|
541
|
+
While using Drupal to render components offers tighter integration, there are strong reasons to use Twig.js or Twing in many scenarios:
|
|
542
|
+
|
|
543
|
+
- 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 or Twing provide sufficient rendering without the need for full Drupal preprocessing.
|
|
544
|
+
- **Twig.js** works well for most frontend-focused use cases.
|
|
545
|
+
- **Twing** is a modern, actively maintained Twig implementation for Node.js that offers better compatibility with Drupal's Twig features and syntax.
|
|
546
|
+
- Styling and behavior mismatches can be managed separately in the Drupal implementation phase.
|
|
547
|
+
|
|
528
548
|
## Dependencies
|
|
529
549
|
|
|
530
550
|
- [vite-plugin-twig-drupal](https://github.com/larowlan/vite-plugin-twig-drupal): Loads Twig with Drupal functions in twig.js.
|
|
531
551
|
- [vite-plugin-twing-drupal](https://github.com/christianwiedemann/vite-plugin-twing-drupal): Loads Twig with Drupal functions in Twing.
|
|
532
|
-
- [json-schema-faker](https://github.com/json-schema-faker/json-schema-faker): Generates mock data for missing props and
|
|
552
|
+
- [json-schema-faker](https://github.com/json-schema-faker/json-schema-faker): Generates mock data for missing props and slots.
|
|
533
553
|
- [JSON Schema validator](https://www.npmjs.com/package/jsonschema)
|
|
534
554
|
|
|
535
555
|
## Known Issues
|
|
@@ -538,5 +558,5 @@ const config = {
|
|
|
538
558
|
|
|
539
559
|
## UI Patterns
|
|
540
560
|
|
|
541
|
-
- Variants partially supported ([Issue 3390712](https://www.drupal.org/project/drupal/issues/3390712)).
|
|
561
|
+
- Variants are partially supported ([Issue 3390712](https://www.drupal.org/project/drupal/issues/3390712)).
|
|
542
562
|
- 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)).
|
package/dist/preset.js
CHANGED
|
@@ -112,7 +112,7 @@ var renderImage = (item) => {
|
|
|
112
112
|
`<img src="${item.uri}"${toAttributes(item.attributes)}>`
|
|
113
113
|
);
|
|
114
114
|
};
|
|
115
|
-
var
|
|
115
|
+
var renderElement = (item) => {
|
|
116
116
|
return JSON.stringify(
|
|
117
117
|
`<${item.tag ?? "div"}${toAttributes(item.attributes)}> ${item.value} </${item.tag ?? "div"}>`
|
|
118
118
|
);
|
|
@@ -132,8 +132,8 @@ var defaultStoryNodes = [
|
|
|
132
132
|
priority: -1
|
|
133
133
|
},
|
|
134
134
|
{
|
|
135
|
-
appliesTo: (item) => item?.type === "
|
|
136
|
-
render: (item) =>
|
|
135
|
+
appliesTo: (item) => item?.type === "element" || item?.theme === "element",
|
|
136
|
+
render: (item) => renderElement(item),
|
|
137
137
|
priority: -2
|
|
138
138
|
},
|
|
139
139
|
{
|