storybook-addon-sdc 0.25.1 → 0.27.0
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 +32 -12
- package/dist/index.d.ts +217 -0
- package/dist/preset.js +2240 -1877
- package/dist/renderer/twig.js +68 -42
- package/dist/renderer/twing.js +78 -53
- package/package.json +32 -27
package/README.md
CHANGED
|
@@ -128,6 +128,24 @@ const config = {
|
|
|
128
128
|
export default config
|
|
129
129
|
```
|
|
130
130
|
|
|
131
|
+
In a TypeScript config (`.storybook/main.ts`) the addon options are typed:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
import type { StorybookConfig } from '@storybook/html-vite'
|
|
135
|
+
import type { SDCAddonOptions } from 'storybook-addon-sdc'
|
|
136
|
+
|
|
137
|
+
const sdcOptions: SDCAddonOptions = {
|
|
138
|
+
sdcStorybookOptions: { twigLib: 'twing' },
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
const config: StorybookConfig = {
|
|
142
|
+
stories: ['../components/**/*.component.yml'],
|
|
143
|
+
addons: [{ name: 'storybook-addon-sdc', options: sdcOptions }],
|
|
144
|
+
framework: { name: '@storybook/html-vite', options: {} },
|
|
145
|
+
}
|
|
146
|
+
export default config
|
|
147
|
+
```
|
|
148
|
+
|
|
131
149
|
## Creating Stories
|
|
132
150
|
|
|
133
151
|
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:
|
|
@@ -263,7 +281,7 @@ A leaf, returning HTML — e.g. a YouTube embed reused across stories:
|
|
|
263
281
|
sdcStorybookOptions: {
|
|
264
282
|
customNodes: [
|
|
265
283
|
{
|
|
266
|
-
match: item => item
|
|
284
|
+
match: (item) => item.type === 'youtube',
|
|
267
285
|
render: item =>
|
|
268
286
|
`<iframe src="https://www.youtube.com/embed/${item.id}" allowfullscreen></iframe>`,
|
|
269
287
|
},
|
|
@@ -283,7 +301,7 @@ the pipeline:
|
|
|
283
301
|
```js
|
|
284
302
|
customNodes: [
|
|
285
303
|
{
|
|
286
|
-
match: (item) => item
|
|
304
|
+
match: (item) => item.type === 'link',
|
|
287
305
|
render: (item) => ({
|
|
288
306
|
type: 'element',
|
|
289
307
|
tag: 'a',
|
|
@@ -706,7 +724,7 @@ $schema: https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schema
|
|
|
706
724
|
|
|
707
725
|
- **Validation Warnings:** Validation errors or warnings are logged to the console, helping developers identify any issues with component configurations. **Note:** Validation will not break the rendering of the components. Even if a validation error occurs, the component will still appear in Storybook, and the warning will be logged for review.
|
|
708
726
|
|
|
709
|
-
To enable validation, set `validate: URL of schema
|
|
727
|
+
To enable validation, set `validate: true` (Drupal core's schema) or pass the URL of your own default schema:
|
|
710
728
|
|
|
711
729
|
```js
|
|
712
730
|
const config = {
|
|
@@ -716,8 +734,8 @@ const config = {
|
|
|
716
734
|
name: 'storybook-addon-sdc',
|
|
717
735
|
options: {
|
|
718
736
|
sdcStorybookOptions: {
|
|
719
|
-
|
|
720
|
-
|
|
737
|
+
// true = https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schemas/v1/metadata.schema.json
|
|
738
|
+
validate: true,
|
|
721
739
|
},
|
|
722
740
|
},
|
|
723
741
|
},
|
|
@@ -725,6 +743,8 @@ const config = {
|
|
|
725
743
|
}
|
|
726
744
|
```
|
|
727
745
|
|
|
746
|
+
A component's own `$schema` always takes precedence over the default. Validation only warns: a failing or unreachable schema never removes a component from Storybook.
|
|
747
|
+
|
|
728
748
|
### `useBasicArgsForStories`
|
|
729
749
|
|
|
730
750
|
By default, when generating stories for your SDC components, the addon automatically spreads the `Basic.args` into each generated story. This behavior can be controlled using the `useBasicArgsForStories` option.
|
|
@@ -832,13 +852,13 @@ thirdPartySettings:
|
|
|
832
852
|
|
|
833
853
|
Below is a list of all available configuration options for `thirdPartySettings.sdcStorybook`:
|
|
834
854
|
|
|
835
|
-
| Key | Type | Description
|
|
836
|
-
| ----------------- | -------- |
|
|
837
|
-
| `tags` | `array` | Optional. Adds additional [Storybook tags](https://storybook.js.org/docs/writing-docs/autodocs) (e.g. `autodocs`).
|
|
838
|
-
| `disabledStories` | `array` | Optional. Array of story names to disable. Supports `basic`, `preview`, or any custom story name. Use `all` to disable all stories.
|
|
839
|
-
| `parameters` | `object` | Global [Storybook parameters](https://storybook.js.org/docs/writing-stories/parameters) applied to all generated stories.
|
|
840
|
-
| `globals` | `object` | Global [Storybook globals](https://storybook.js.org/docs/essentials/toolbars-and-globals) applied to all generated stories. Story-level `globals` override component-level values.
|
|
841
|
-
| `stories` | `object` | Allows defining or overriding specific stories. Each key (e.g. `preview`) represents a story. Within each story, you can define `props`, `slots`, `parameters`, `globals`, `description`, `name`, and `library_wrapper`.
|
|
855
|
+
| Key | Type | Description |
|
|
856
|
+
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
857
|
+
| `tags` | `array` | Optional. Adds additional [Storybook tags](https://storybook.js.org/docs/writing-docs/autodocs) (e.g. `autodocs`). |
|
|
858
|
+
| `disabledStories` | `array` | Optional. Array of story names to disable. Supports `basic`, `preview`, or any custom story name. Use `all` to disable all stories. |
|
|
859
|
+
| `parameters` | `object` | Global [Storybook parameters](https://storybook.js.org/docs/writing-stories/parameters) applied to all generated stories. |
|
|
860
|
+
| `globals` | `object` | Global [Storybook globals](https://storybook.js.org/docs/essentials/toolbars-and-globals) applied to all generated stories. Story-level `globals` override component-level values. |
|
|
861
|
+
| `stories` | `object` | Allows defining or overriding specific stories. Each key (e.g. `preview`) represents a story. Within each story, you can define `props`, `slots`, `parameters`, `globals`, `description`, `name`, and `library_wrapper`. |
|
|
842
862
|
|
|
843
863
|
### Disabled Stories Examples
|
|
844
864
|
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
import { JSONSchema4 } from 'json-schema';
|
|
2
|
+
import { GenerateOptions } from 'json-schema-faker';
|
|
3
|
+
import { Parameters } from '@storybook/html-vite';
|
|
4
|
+
import { Globals } from 'storybook/internal/types';
|
|
5
|
+
import Twig from 'twig';
|
|
6
|
+
|
|
7
|
+
// A user-defined render node: `match` selects it, `render` returns HTML or
|
|
8
|
+
// another node. Works in plain and wrapper slots; Twing Maps arrive as objects.
|
|
9
|
+
interface CustomNode {
|
|
10
|
+
match: (item: Record<string, unknown>) => boolean
|
|
11
|
+
render: (item: Record<string, unknown>) => string | object
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
interface SDCSchema {
|
|
15
|
+
$schema?: string
|
|
16
|
+
// Keyed by `$ref`, e.g. `ui-patterns://links`.
|
|
17
|
+
$defs?: Record<string, JSONSchema4>
|
|
18
|
+
name: string
|
|
19
|
+
description?: string
|
|
20
|
+
group?: string
|
|
21
|
+
status?: 'experimental' | 'stable' | 'deprecated' | 'obsolete'
|
|
22
|
+
props?: JSONSchema4
|
|
23
|
+
slots?: SlotDefinition
|
|
24
|
+
libraryOverrides?: LibraryDefinition
|
|
25
|
+
thirdPartySettings?: ThirdPartySettings
|
|
26
|
+
// Drupal 11.2+ variants.
|
|
27
|
+
variants?: Record<string, VariantDefinition>
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
interface VariantDefinition {
|
|
31
|
+
title: string
|
|
32
|
+
description?: string
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
interface SlotDefinition {
|
|
36
|
+
[key: string]: {
|
|
37
|
+
title?: string
|
|
38
|
+
description?: string
|
|
39
|
+
examples?: string[]
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
interface CssFileOptions {
|
|
44
|
+
attributes?: Record<string, string | boolean>
|
|
45
|
+
group?: string
|
|
46
|
+
media?: string
|
|
47
|
+
minified?: boolean
|
|
48
|
+
preprocess?: boolean
|
|
49
|
+
type?: string
|
|
50
|
+
weight?: number
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* One CSS group (base / layout / component / state / theme). Keys are file
|
|
55
|
+
* paths or URLs. A `false` value disables an asset, matching Drupal's
|
|
56
|
+
* `libraryOverrides` semantics.
|
|
57
|
+
*/
|
|
58
|
+
type CssGroup = Record<string, CssFileOptions | false>
|
|
59
|
+
|
|
60
|
+
interface CssSection {
|
|
61
|
+
base?: CssGroup
|
|
62
|
+
layout?: CssGroup
|
|
63
|
+
component?: CssGroup
|
|
64
|
+
state?: CssGroup
|
|
65
|
+
theme?: CssGroup
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
interface JsFileOptions {
|
|
69
|
+
attributes?: Record<string, string | boolean>
|
|
70
|
+
preprocess?: boolean
|
|
71
|
+
type?: string
|
|
72
|
+
weight?: number
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Keys are file paths or URLs. A `false` value disables an asset, matching
|
|
77
|
+
* Drupal's `libraryOverrides` semantics.
|
|
78
|
+
*/
|
|
79
|
+
type JsSection = Record<string, JsFileOptions | false>
|
|
80
|
+
|
|
81
|
+
interface LibraryDefinition {
|
|
82
|
+
dependencies?: string[]
|
|
83
|
+
css?: CssSection
|
|
84
|
+
js?: JsSection
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
interface ExternalCssAsset {
|
|
88
|
+
type: 'css'
|
|
89
|
+
url: string
|
|
90
|
+
media?: string
|
|
91
|
+
attributes?: Record<string, string | boolean>
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
interface ExternalJsAsset {
|
|
95
|
+
type: 'js'
|
|
96
|
+
url: string
|
|
97
|
+
attributes?: Record<string, string | boolean>
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
type ExternalAsset = ExternalCssAsset | ExternalJsAsset
|
|
101
|
+
|
|
102
|
+
// The addon reads `sdcStorybook`; other modules keep their own keys.
|
|
103
|
+
interface ThirdPartySettings {
|
|
104
|
+
sdcStorybook?: SDCStorybookSettings
|
|
105
|
+
[key: string]: unknown
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
interface SDCStorybookSettings {
|
|
109
|
+
tags?: string[]
|
|
110
|
+
disabledStories?: string[]
|
|
111
|
+
parameters?: Parameters
|
|
112
|
+
globals?: Globals
|
|
113
|
+
stories?: Record<string, StoryDefinition>
|
|
114
|
+
}
|
|
115
|
+
interface NamespaceDefinition {
|
|
116
|
+
namespace?: string
|
|
117
|
+
namespaces?: Record<string, string>
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
type ResolveIconSource = (
|
|
121
|
+
source: string,
|
|
122
|
+
context: { packId: string; namespace: string }
|
|
123
|
+
) => string
|
|
124
|
+
|
|
125
|
+
interface SDCStorybookOptions extends NamespaceDefinition {
|
|
126
|
+
experimentalVariants?: boolean
|
|
127
|
+
useBasicArgsForStories?: boolean
|
|
128
|
+
customNodes?: CustomNode[]
|
|
129
|
+
dependencyMap?: Record<string, ExternalAsset[]>
|
|
130
|
+
resolveIconSource?: ResolveIconSource
|
|
131
|
+
twigLib?: 'twing' | 'twig'
|
|
132
|
+
customDefs?: {
|
|
133
|
+
[key: string]: JSONSchema4
|
|
134
|
+
}
|
|
135
|
+
externalDefs?: string[]
|
|
136
|
+
validate?: string | boolean
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// A story from `sdcStorybook.stories` or a *.story.yml. Prop and slot values
|
|
140
|
+
// are YAML: scalars, render nodes or arrays of them.
|
|
141
|
+
interface StoryDefinition {
|
|
142
|
+
name?: string
|
|
143
|
+
description?: string
|
|
144
|
+
props?: Record<string, unknown>
|
|
145
|
+
slots?: Record<string, unknown>
|
|
146
|
+
variants?: Record<string, VariantDefinition>
|
|
147
|
+
library_wrapper?: string
|
|
148
|
+
parameters?: Parameters
|
|
149
|
+
globals?: Globals
|
|
150
|
+
thirdPartySettings?: {
|
|
151
|
+
sdcStorybook?: Pick<SDCStorybookSettings, 'parameters' | 'globals'>
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
// `type: component` node: embeds a component, optionally from a story's args.
|
|
156
|
+
interface ComponentNode {
|
|
157
|
+
type: 'component'
|
|
158
|
+
component: string
|
|
159
|
+
props?: Record<string, unknown>
|
|
160
|
+
slots?: Record<string, unknown>
|
|
161
|
+
story?: string
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
interface VitePluginTwingDrupalOptions {
|
|
165
|
+
namespaces?: Record<string, string[]>
|
|
166
|
+
include?: string | RegExp
|
|
167
|
+
hooks?: string
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
interface VitePluginTwigDrupalOptions {
|
|
171
|
+
namespaces?: Record<string, string>
|
|
172
|
+
// Serialized into each compiled template and called with twig.js.
|
|
173
|
+
functions?: Record<string, (twig: typeof Twig) => void>
|
|
174
|
+
globalContext?: Record<string, unknown>
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
interface SDCAddonOptions {
|
|
178
|
+
sdcStorybookOptions: SDCStorybookOptions
|
|
179
|
+
vitePluginTwingDrupalOptions?: VitePluginTwingDrupalOptions
|
|
180
|
+
vitePluginTwigDrupalOptions?: VitePluginTwigDrupalOptions
|
|
181
|
+
jsonSchemaFakerOptions?: GenerateOptions
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
// *.icons.yml `settings`; `default` applies when icon() omits the key.
|
|
185
|
+
type IconPackSettings = Record<string, { default?: unknown }>
|
|
186
|
+
|
|
187
|
+
// Any other extractor still renders, like `path` (source and icon_id).
|
|
188
|
+
type KnownIconExtractor = 'svg_sprite' | 'svg' | 'path'
|
|
189
|
+
type IconExtractor = KnownIconExtractor | (string & {})
|
|
190
|
+
|
|
191
|
+
interface SvgIconData {
|
|
192
|
+
content: string
|
|
193
|
+
attrs: Record<string, string>
|
|
194
|
+
sourceUrl: string
|
|
195
|
+
group: string
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
interface PathIconData {
|
|
199
|
+
sourceUrl: string
|
|
200
|
+
group: string
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
interface IconPack {
|
|
204
|
+
packId: string
|
|
205
|
+
label: string
|
|
206
|
+
extractor: IconExtractor
|
|
207
|
+
sources: string[]
|
|
208
|
+
sourceUrls: string[]
|
|
209
|
+
settings: IconPackSettings
|
|
210
|
+
template: string
|
|
211
|
+
svgIcons: Record<string, SvgIconData>
|
|
212
|
+
pathIcons: Record<string, PathIconData>
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
type IconPacks = Record<string, IconPack>
|
|
216
|
+
|
|
217
|
+
export type { ComponentNode, CssFileOptions, CssGroup, CssSection, CustomNode, ExternalAsset, ExternalCssAsset, ExternalJsAsset, IconExtractor, IconPack, IconPackSettings, IconPacks, JsFileOptions, JsSection, KnownIconExtractor, LibraryDefinition, NamespaceDefinition, ResolveIconSource, SDCAddonOptions, SDCSchema, SDCStorybookOptions, SDCStorybookSettings, StoryDefinition, ThirdPartySettings, VariantDefinition, VitePluginTwigDrupalOptions, VitePluginTwingDrupalOptions };
|