storybook-addon-sdc 0.0.12 → 0.0.14

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 (2) hide show
  1. package/README.md +92 -199
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,233 +1,126 @@
1
- # Storybook Addon Storybook Addon SDC
1
+ # Storybook SDC Addon Documentation
2
2
  Drupal Single Directory Components as stories
3
3
 
4
- ### Development scripts
4
+ ## Overview:
5
5
 
6
- - `npm run start` runs babel in watch mode and starts Storybook
7
- - `npm run build` build and package your addon code
6
+ This Storybook addon streamlines the integration of Drupal Single Directory Components (SDC) into Storybook. It leverages YAML configurations and Twig templates to dynamically load components and generate stories with minimal configuration.
8
7
 
9
- ### Switch from TypeScript to JavaScript
8
+ ## The addon includes:
10
9
 
11
- Don't want to use TypeScript? We offer a handy eject command: `npm run eject-ts`
10
+ - A Vite plugin to load YAML-based SDC configurations.
11
+ - Dynamic path resolution based on namespaces for component discovery.
12
+ - A story generator to create component stories from YAML files.
13
+ - Support for JSON schema-based props and Drupal behaviors.
12
14
 
13
- This will convert all code to JS. It is a destructive process, so we recommended running this before you start writing any code.
15
+ ## This addon uses:
14
16
 
15
- ## What's included?
17
+ - https://github.com/larowlan/vite-plugin-twig-drupal for load Twig with Drupal functions.
18
+ - https://github.com/json-schema-faker/json-schema-faker for generation missed props and slots.
16
19
 
17
- ![Demo](https://user-images.githubusercontent.com/42671/107857205-e7044380-6dfa-11eb-8718-ad02e3ba1a3f.gif)
20
+ ## Installation:
18
21
 
19
- The addon code lives in `src`. It demonstrates all core addon related concepts. The three [UI paradigms](https://storybook.js.org/docs/react/addons/addon-types#ui-based-addons)
20
-
21
- - `src/Tool.tsx`
22
- - `src/Panel.tsx`
23
- - `src/Tab.tsx`
24
-
25
- Which, along with the addon itself, are registered in `src/manager.ts`.
26
-
27
- Managing State and interacting with a story:
28
-
29
- - `src/withGlobals.ts` & `src/Tool.tsx` demonstrates how to use `useGlobals` to manage global state and modify the contents of a Story.
30
- - `src/withRoundTrip.ts` & `src/Panel.tsx` demonstrates two-way communication using channels.
31
- - `src/Tab.tsx` demonstrates how to use `useParameter` to access the current story's parameters.
32
-
33
- Your addon might use one or more of these patterns. Feel free to delete unused code. Update `src/manager.ts` and `src/preview.ts` accordingly.
34
-
35
- Lastly, configure you addon name in `src/constants.ts`.
36
-
37
- ### Bundling
38
-
39
- Addons can interact with a Storybook project in multiple ways. It is recommended to familiarize yourself with [the basics](https://storybook.js.org/docs/react/addons/introduction) before getting started.
40
-
41
- - Manager entries are used to add UI or behavior to the Storybook manager UI.
42
- - Preview entries are used to add UI or behavior to the preview iframe where stories are rendered.
43
- - Presets are used to modify the Storybook configuration, similar to how [users can configure their `main.ts` configurations](https://storybook.js.org/docs/react/api/main-config).
44
-
45
- Since each of these places represents a different environment with different features and modules, it is also recommended to split and build your modules accordingly. This addon-kit comes with a preconfigured [bundling configuration](./tsup.config.ts) that supports this split, and you are free to modify and extend it as needed.
46
-
47
- You can define which modules match which environments in the [`package.json#bundler`](./package.json) property:
48
-
49
- - `exportEntries` is a list of module entries that users can manually import from anywhere they need to. For example, you could have decorators that users need to import into their `preview.ts` file or utility functions that can be used in their `main.ts` files.
50
- - `managerEntries` is a list of module entries meant only for the manager UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.
51
- - `previewEntries` is a list of module entries meant only for the preview UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.
52
-
53
- Manager and preview entries are only used in the browser so they only output ESM modules. Export entries could be used both in the browser and in Node depending on their use case, so they both output ESM and CJS modules.
54
-
55
- #### Globalized packages
56
-
57
- Storybook provides a predefined set of packages that are available in the manager UI and the preview UI. In the final bundle of your addon, these packages should not be included. Instead, the imports should stay in place, allowing Storybook to replace those imports with the actual packages during the Storybook build process.
58
-
59
- The list of packages differs between the manager and the preview, which is why there is a slight difference between `managerEntries` and `previewEntries`. Most notably, `react` and `react-dom` are prebundled in the manager but not in the preview. This means that your manager entries can use React to build UI without bundling it or having a direct reference to it. Therefore, it is safe to have React as a `devDependency` even though you are using it in production. _Requiring React as a peer dependency would unnecessarily force your users to install React._
60
-
61
- An exception to this rule is if you are using React to inject UI into the preview, which does not come prebundled with React. In such cases, you need to move `react` and `react-dom` to a peer dependency. However, we generally advise against this pattern since it would limit the usage of your addon to React-based Storybooks.
62
-
63
- ### Metadata
64
-
65
- Storybook addons are listed in the [catalog](https://storybook.js.org/addons) and distributed via npm. The catalog is populated by querying npm's registry for Storybook-specific metadata in `package.json`. This project has been configured with sample data. Learn more about available options in the [Addon metadata docs](https://storybook.js.org/docs/react/addons/addon-catalog#addon-metadata).
66
-
67
- ## Documentation
68
-
69
- To help the community use your addon and understand its capabilities, please document it thoroughly.
70
-
71
- To get started, replace this README with the content in this sample template, modeled after how essential addons (like [Actions](https://storybook.js.org/docs/essentials/actions)) are documented. Then update the content to describe your addon.
72
-
73
- ### Sample documentation template
74
-
75
- ````md
76
- # My Addon
77
-
78
- ## Installation
79
-
80
- First, install the package.
81
-
82
- ```sh
83
- npm install --save-dev my-addon
84
22
  ```
85
-
86
- Then, register it as an addon in `.storybook/main.js`.
87
-
88
- ```js
89
- // .storybook/main.ts
90
-
91
- // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
92
- import type { StorybookConfig } from '@storybook/your-framework';
93
-
94
- const config: StorybookConfig = {
95
- // ...rest of config
96
- addons: [
97
- '@storybook/addon-essentials'
98
- 'my-addon', // 👈 register the addon here
99
- ],
100
- };
101
-
102
- export default config;
23
+ npm i storybook-addon-sdc
103
24
  ```
104
25
 
105
- ## Usage
106
-
107
- The primary way to use this addon is to define the `exampleParameter` parameter. You can do this the
108
- component level, as below, to affect all stories in the file, or you can do it for a single story.
109
-
110
- ```js
111
- // Button.stories.ts
26
+ ## Configuration:
112
27
 
113
- // Replace your-framework with the name of your framework
114
- import type { Meta } from '@storybook/your-framework';
28
+ In vite-html storybook https://storybook.js.org/docs/builders/vite
115
29
 
116
- import { Button } from './Button';
117
-
118
- const meta: Meta<typeof Button> = {
119
- component: Button,
120
- parameters: {
121
- myAddon: {
122
- exampleParameter: true,
123
- // See API section below for available parameters
124
- }
125
- }
126
- };
127
-
128
- export default meta;
30
+ main.ts
129
31
  ```
130
-
131
- Another way to use the addon is...
132
-
133
- ## API
134
-
135
- ### Parameters
136
-
137
- This addon contributes the following parameters to Storybook, under the `myAddon` namespace:
138
-
139
- #### `disable`
140
-
141
- Type: `boolean`
142
-
143
- Disable this addon's behavior. This parameter is most useful to allow overriding at more specific
144
- levels. For example, if this parameter is set to true at the project level, it could then be
145
- re-enabled by setting it to false at the meta (component) or story level.
146
-
147
- ### Options
148
-
149
- When registering this addon, you can configure it with the following options, which are passed when
150
- registering the addon, like so:
151
-
152
- ```ts
153
- // .storybook/main.ts
154
-
155
- // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
156
- import type { StorybookConfig } from '@storybook/your-framework';
32
+ import type { StorybookConfig } from "@storybook/html-vite";
157
33
 
158
34
  const config: StorybookConfig = {
159
- // ...rest of config
35
+ stories: ["../components/**/*.component.yml"], // Your components directory.
160
36
  addons: [
161
- '@storybook/essentials',
162
37
  {
163
- name: 'my-addon',
38
+ name: "storybook-addon-sdc",
164
39
  options: {
165
- // 👈 options for my-addon go here
166
- },
40
+ sdcStorybookOptions: {
41
+ namespace: "umami", // Your namespace.
42
+ },
43
+ vitePluginTwigDrupalOptions: {}, // vite-plugin-twig-drupal options.
44
+ jsonSchemaFakerOptions: {}, // json-schema-faker options
45
+ }
167
46
  },
47
+ "@storybook/addon-essentials", // Other addons.
168
48
  ],
49
+ framework: {
50
+ name: "@storybook/html-vite",
51
+ options: {},
52
+ },
169
53
  };
170
-
171
54
  export default config;
172
55
  ```
173
56
 
174
- #### `useExperimentalBehavior`
57
+ ## Idea:
175
58
 
176
- Type: `boolean`
59
+ By default addon generates only Basic story for every component.
177
60
 
178
- Enable experimental behavior to...
61
+ To create new stories you may use thirdPartySettings in SDC yaml:
179
62
 
180
- ````
181
-
182
- ## Release Management
183
-
184
- ### Setup
185
-
186
- This project is configured to use [auto](https://github.com/intuit/auto) for release management. It generates a changelog and pushes it to both GitHub and npm. Therefore, you need to configure access to both:
187
-
188
- - [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-access-tokens) Create a token with both _Read and Publish_ permissions.
189
- - [`GH_TOKEN`](https://github.com/settings/tokens) Create a token with the `repo` scope.
190
-
191
- Then open your `package.json` and edit the following fields:
192
-
193
- - `name`
194
- - `author`
195
- - `repository`
196
-
197
- #### Local
198
-
199
- To use `auto` locally create a `.env` file at the root of your project and add your tokens to it:
200
-
201
- ```bash
202
- GH_TOKEN=<value you just got from GitHub>
203
- NPM_TOKEN=<value you just got from npm>
204
63
  ```
205
-
206
- Lastly, **create labels on GitHub**. You’ll use these labels in the future when making changes to the package.
207
-
208
- ```bash
209
- npx auto create-labels
64
+ $schema: https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schemas/v1/metadata.schema.json
65
+
66
+ name: Card
67
+ status: experimental
68
+ props:
69
+ type: object
70
+ properties:
71
+ html_tag:
72
+ type: string
73
+ title: HTML tag for wrapper
74
+ enum:
75
+ - article
76
+ - div
77
+ default: article
78
+
79
+ slots:
80
+ content:
81
+ title: Content
82
+ required: true
83
+ description: The card content.
84
+ examples:
85
+ - Hello! I'm card content
86
+
87
+ thirdPartySettings:
88
+ sdcStorybook:
89
+ stories:
90
+ preview:
91
+ title: Preview
92
+ args:
93
+ html_tag: "div"
94
+ content:
95
+ - type: component
96
+ component: "umami:title"
97
+ args:
98
+ label: test
99
+ - type: component
100
+ component: "umami:read-more"
101
+ args:
102
+ text: test
103
+ url: '#'
104
+ preview2:
105
+ title: Preview 2
106
+ args:
107
+ html_tag: "div"
108
+ content:
109
+ - type: component
110
+ component: "umami:title"
111
+ args:
112
+ label: test 2
113
+ extra_classes:
114
+ - 'card__title'
115
+ - type: component
116
+ component: "umami:read-more"
117
+ args:
118
+ text: test
119
+ url: '#'
120
+ extra_classes:
121
+ - 'card__read-more'
210
122
  ```
211
123
 
212
- If you check on GitHub, you’ll now see a set of labels that `auto` would like you to use. Use these to tag future pull requests.
213
-
214
- #### GitHub Actions
215
-
216
- This template comes with GitHub actions already set up to publish your addon anytime someone pushes to your repository.
217
-
218
- Go to `Settings > Secrets`, click `New repository secret`, and add your `NPM_TOKEN`.
219
-
220
- ### Creating a release
221
-
222
- To create a release locally you can run the following command, otherwise the GitHub action will make the release for you.
223
-
224
- ```sh
225
- npm run release
226
- ```
227
124
 
228
- That will:
125
+ Or you can import yaml in regular storybook *.stories.js
229
126
 
230
- - Build and package the addon code
231
- - Bump the version
232
- - Push a release to GitHub and npm
233
- - Push a changelog to GitHub
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "storybook-addon-sdc",
3
- "version": "0.0.12",
3
+ "version": "0.0.14",
4
4
  "description": "Drupal Single Directory Components as stories",
5
5
  "keywords": [
6
6
  "SDC",