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 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?.type === 'youtube',
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?.type === 'link',
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
- validate:
720
- 'https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schemas/v1/metadata.schema.json',
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. **Note:** `disableBasicStory` is deprecated in favor of `disabledStories: ['basic']`. |
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
 
@@ -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 };