feat: 🎸 feat(tool-storybook): add vanilla JS support and preview configuration helpers

- Add createPreviewConfig helper for simplified Storybook setup
- Add createVanillaRenderer for vanilla JavaScript widget rendering
- Add comprehensive JSDoc documentation for all exported functions
- Update documentation with Storybook 9 setup for both Preact and vanilla JS widgets
- Include separate configuration examples for Preact and vanilla frameworks

Author: Jiří Fencl

packages/tool-storybook/src/index.js

@@ -1,5 +1,15 @@
-import { getMerkur } from '@merkur/core';
+import { getMerkur, createMerkurWidget } from '@merkur/core';
 
+/**
+ * Creates a loader function for Storybook that manages Merkur widget lifecycle.
+ * The loader creates and mounts widgets for stories, reusing instances when possible
+ * and unmounting previous widgets when switching stories.
+ *
+ * @param {Object} options Configuration options
+ * @param {Object} options.widgetProperties The widget properties used to create widget instances
+ * @param {Function} options.render Callback function called when widget state updates
+ * @returns {Function} Async loader function that returns widget instance for stories
+ */
 function createWidgetLoader({ render, widgetProperties }) {
   let lastStory = {};
 
@@ -40,4 +50,62 @@ function createWidgetLoader({ render, widgetProperties }) {
   };
 }
 
-export { createWidgetLoader };
+/**
+ * Creates a Storybook preview configuration for Merkur widgets.
+ * Handles widget registration and loader setup.
+ *
+ * @param {Object} options Configuration options
+ * @param {Object} options.widgetProperties The widget properties to register
+ * @param {Function} [options.render] Optional custom render function for widget updates
+ * @param {Function} [options.createWidget=createMerkurWidget] Factory function to create widget instances
+ * @returns {Object} Storybook preview configuration with loaders
+ */
+function createPreviewConfig({
+  widgetProperties,
+  render,
+  createWidget = createMerkurWidget,
+}) {
+  // Register the widget with Merkur
+  getMerkur().register({
+    ...widgetProperties,
+    createWidget,
+  });
+
+  return {
+    loaders: [
+      createWidgetLoader({
+        widgetProperties,
+        render: render || (() => {}),
+      }),
+    ],
+  };
+}
+
+/**
+ * Creates a render function for vanilla JavaScript widgets.
+ * Renders widget using HTML string output.
+ *
+ * @param {Function|Object} ViewComponent The view function or component map
+ * @returns {Function} Storybook render function
+ */
+function createVanillaRenderer(ViewComponent) {
+  // eslint-disable-next-line no-unused-vars
+  return (args, { loaded: { widget }, viewMode }) => {
+    if (!widget) {
+      return document.createElement('div');
+    }
+
+    const container = document.createElement('div');
+    const viewFunction =
+      typeof ViewComponent === 'function'
+        ? ViewComponent
+        : args.viewComponent && ViewComponent[args.viewComponent]
+          ? ViewComponent[args.viewComponent]
+          : ViewComponent.default || ViewComponent;
+
+    container.innerHTML = viewFunction(widget);
+    return container;
+  };
+}
+
+export { createWidgetLoader, createPreviewConfig, createVanillaRenderer };

website/docs/storybook-integration-into-merkur.md

@@ -8,72 +8,149 @@ description: Learn how to integrate Storybook with your Merkur widget
 
 [Storybook](https://storybook.js.org/) is an open source tool for developing UI components in isolation for React, Vue, Angular, and more. It makes building stunning UIs organized and efficient.
 
+This guide requires Storybook version 9 or higher. Lower versions need a different setup, which is covered in previous versions of the documentation.
+
 ## Installation
 
-At first we must install storybook to our Merkur project. The best way is using the [Storybook CLI](https://storybook.js.org/docs/react/get-started/install) to install it in a single command.
+Since Preact and vanilla JavaScript are not in the automatic framework selection, you need to manually install Storybook packages.
+
+### For Preact Widgets
 
 ```bash
-npx storybook@latest init
+npm i -D @storybook/preact-vite storybook
 ```
 
-After that we install merkur module for easy integration.
+### For Vanilla JavaScript Widgets
 
 ```bash
-npm i @merkur/tool-storybook --save-dev
+npm i -D @storybook/html-vite storybook
 ```
 
-Now we must update storybook file `./storybook/preview.js` similarly to the example below.
+### Merkur Integration Package
+
+Then install the Merkur module for easy integration (required for both):
+
+```bash
+npm i -D @merkur/tool-storybook
+```
+
+## Configuration
+
+### Preact Widget
+
+For Preact widgets, configure Storybook to use the Preact framework and JSX transformation.
+
+#### `.storybook/main.mjs`
 
 ```javascript
-// ./storybook/preview.js
-import { createPreactWidget } from '@merkur/preact/client';
+const config = {
+  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  framework: {
+    name: '@storybook/preact-vite',
+  },
+  // Configure Vite to transform JSX to Preact's `h` function instead of React's `React.createElement`
+  // This automatically injects Preact imports so you don't need to import h and Fragment in every file
+  async viteFinal(config) {
+    config.esbuild = {
+      jsxFactory: 'h',
+      jsxFragment: 'Fragment',
+      jsxInject: `import { h, Fragment } from 'preact'`,
+    };
+    return config;
+  },
+};
+
+export default config;
+```
 
-// helper method for creating storybook loader, which async creates our widget instance.
-import { createWidgetLoader } from '@merkur/tool-storybook';
+#### `.storybook/preview.mjs`
 
-// Imports for updating storybook playground.
-import { FORCE_RE_RENDER } from '@storybook/core-events';
-import { addons } from '@storybook/preview-api';
+```javascript
+import { h, render } from 'preact';
+import { createPreviewConfig } from '@merkur/tool-storybook';
+import widgetProperties from '../src/widget.js';
+import View from '../src/views/View.jsx';
+import HeadlineSlot from '../src/slots/HeadlineSlot.jsx';
 
-import WidgetContext from '../src/components/WidgetContext';
-// receive widget properties for creating our Merkur widget instance
-import widgetProperties from '../src/widget';
+// Create preview configuration with Merkur widget support
+const preview = {
+    ...createPreviewConfig({
+        widgetProperties,
+    }),
+    // Preact render function
+    render: (args, { loaded: { widget }, viewMode }) => {
+        if (!widget) {
+            return document.createElement('div');
+        }
 
-// register our widget to Merkur
-createPreactWidget(widgetProperties);
+        const container = document.createElement('div');
+        const ViewComponent = args.viewComponent === 'headline' ? HeadlineSlot : View;
+        render(h(ViewComponent, widget), container);
 
-// defined our custom widget loader
-export const loaders = [
-  createWidgetLoader({
-    render: () => {
-      addons.getChannel().emit(FORCE_RE_RENDER); // widget must be able to update the storybook playground
+        return container;
     },
-    widgetProperties, // created widget properties
-  })
-];
-
-// if you need Context in React or Preact widget you must define Context Provider.
-export const decorators = [
-   (Story, { loaded: { widget }}) => {
-    return (
-      <WidgetContext.Provider value={widget}>
-        <Story />
-      </WidgetContext.Provider>
-    );
-  },
-];
+};
+
+export default preview;
 ```
 
-> Note: If you use any pre-processors (webpack loaders) for building CSS styles you should also define then in `webpackFinal` function by extending given `config` object. More on that topic can be found in [official Storybook documentation](https://storybook.js.org/docs/react/configure/styling-and-css).
+### Vanilla JavaScript Widget
+
+For vanilla JavaScript widgets that render HTML strings, configure Storybook to use the HTML framework.
 
-That's all. Now we can write our stories.
+#### `.storybook/main.mjs`
+
+```javascript
+const config = {
+  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  framework: {
+    name: '@storybook/html-vite',
+  },
+};
 
-## How to write stories
+export default config;
+```
 
-You can use every [format](https://storybook.js.org/docs/react/writing-stories/introduction) which Storybook offers. For example we pick up `named exports` format and our counter component from demo page for `Preact` preview.
+#### `.storybook/preview.mjs`
 
 ```javascript
-// /src/component/Counter.jsx
+import { createPreviewConfig } from '@merkur/tool-storybook';
+import widgetProperties from '../src/widget.js';
+import View from '../src/views/View.js';
+import HeadlineSlot from '../src/slots/HeadlineSlot.js';
+
+// Create preview configuration with Merkur widget support
+const preview = {
+    ...createPreviewConfig({
+        widgetProperties,
+    }),
+    // Vanilla JS render function
+    render: (args, { loaded: { widget } }) => {
+        if (!widget) {
+            return document.createElement('div');
+        }
+
+        const container = document.createElement('div');
+        const viewFunction = args.viewComponent === 'headline' ? HeadlineSlot : View;
+        container.innerHTML = viewFunction(widget);
+        
+        return container;
+    },
+};
+
+export default preview;
+```
+
+## Writing Stories
+
+You can use any [story format](https://storybook.js.org/docs/react/writing-stories/introduction) that Storybook supports. Below are examples for both Preact and vanilla widgets.
+
+### Preact Widget Stories
+
+For Preact components that use context, wrap them in the appropriate provider:
+
+```jsx
+// /src/components/Counter.jsx
 import { useContext } from 'preact/hooks';
 import WidgetContext from './WidgetContext';
 
@@ -89,22 +166,29 @@ export default function Counter({ counter }) {
     </div>
   );
 }
+```
 
-// /src/component/Counter.stories.jsx
-import Counter from './Counter';
+```jsx
+// /src/components/__tests__/Counter.stories.jsx
+import Counter from '../Counter';
+import WidgetContext from '../WidgetContext';
 
 export default {
   title: 'Counter',
   args: {
     // Every Merkur story must have defined props property
     widget: {
       props: {},
-    }
+    },
   },
 };
 
 const Template = (args, { loaded: { widget } }) => {
-  return <Counter counter={widget.state.counter} />
+  return (
+    <WidgetContext.Provider value={widget}>
+      <Counter counter={widget.state.counter} />
+    </WidgetContext.Provider>
+  );
 };
 
 export const DefaultCounter = Template.bind({});
@@ -116,9 +200,79 @@ TenCounter.args = {
     // change default widget state from 0 to 10
     state: {
       counter: 10,
-      }
-  }
+    },
+  },
 };
 ```
 
-Now run command `npm run storybook` and you will see our Counter component with two settings.
+### Vanilla JavaScript Widget Stories
+
+For vanilla widgets that return HTML strings:
+
+```javascript
+// /src/components/Counter.js
+export default function Counter(widget) {
+  return `
+    <div>
+      <h3>Counter widget:</h3>
+      <p>Count: <span data-merkur="counter">${widget.state.counter}</span></p>
+      <button data-merkur="on-increase">
+        increase counter
+      </button>
+      <button data-merkur="on-reset">
+        reset counter
+      </button>
+    </div>
+  `;
+}
+```
+
+```javascript
+// /src/components/__tests__/Counter.stories.js
+import Counter from '../Counter';
+
+export default {
+  title: 'Counter',
+  args: {
+    // Every Merkur story must have defined props property
+    widget: {
+      props: {},
+    },
+  },
+};
+
+const Template = (args, { loaded: { widget } }) => {
+  const container = document.createElement('div');
+  container.innerHTML = Counter(widget);
+  return container;
+};
+
+export const DefaultCounter = Template.bind({});
+
+export const TenCounter = Template.bind({});
+TenCounter.args = {
+  widget: {
+    props: {},
+    // change default widget state from 0 to 10
+    state: {
+      counter: 10,
+    },
+  },
+};
+```
+
+## Running Storybook
+
+Start Storybook with:
+
+```bash
+npm run storybook
+```
+
+You will see your Counter component with different configurations in the Storybook UI.
+
+## Key Differences
+
+- **Preact widgets**: Use `.jsx` extension, JSX syntax, and component-based rendering with `render(h(Component, props), container)`
+- **Vanilla widgets**: Use `.js` extension, return HTML strings, and render with `container.innerHTML = componentFunction(widget)`
+- **Framework config**: Preact uses `@storybook/preact-vite`, vanilla uses `@storybook/html-vite`