storybook-addon-sdc 0.26.0 → 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 +27 -9
- package/dist/index.d.ts +217 -0
- package/dist/preset.js +3794 -3568
- package/dist/renderer/twig.js +60 -28
- package/dist/renderer/twing.js +78 -53
- package/package.json +16 -7
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',
|
|
@@ -834,13 +852,13 @@ thirdPartySettings:
|
|
|
834
852
|
|
|
835
853
|
Below is a list of all available configuration options for `thirdPartySettings.sdcStorybook`:
|
|
836
854
|
|
|
837
|
-
| Key | Type | Description
|
|
838
|
-
| ----------------- | -------- |
|
|
839
|
-
| `tags` | `array` | Optional. Adds additional [Storybook tags](https://storybook.js.org/docs/writing-docs/autodocs) (e.g. `autodocs`).
|
|
840
|
-
| `disabledStories` | `array` | Optional. Array of story names to disable. Supports `basic`, `preview`, or any custom story name. Use `all` to disable all stories.
|
|
841
|
-
| `parameters` | `object` | Global [Storybook parameters](https://storybook.js.org/docs/writing-stories/parameters) applied to all generated stories.
|
|
842
|
-
| `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.
|
|
843
|
-
| `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`. |
|
|
844
862
|
|
|
845
863
|
### Disabled Stories Examples
|
|
846
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 };
|