@sit-onyx/storybook-utils 1.0.0-beta.6 → 1.0.0-beta.61

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/storybook-utils",
   "description": "Storybook utilities for Vue",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.61",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -23,14 +23,17 @@
     "url": "https://github.com/SchwarzIT/onyx/issues"
   },
   "peerDependencies": {
-    "@storybook/vue3": ">= 8.2.0",
-    "storybook": ">= 8.2.0",
+    "@storybook/vue3": ">= 8.3.0",
+    "storybook": ">= 8.3.0",
     "storybook-dark-mode": ">= 4",
-    "@sit-onyx/icons": "^1.0.0-beta.0",
-    "sit-onyx": "^1.0.0-beta.5"
+    "@sit-onyx/icons": "^1.0.0-beta.6",
+    "sit-onyx": "^1.0.0-beta.55"
   },
   "dependencies": {
-    "deepmerge-ts": "^7.0.3"
+    "deepmerge-ts": "^7.1.1"
+  },
+  "devDependencies": {
+    "vue": "3.5.11"
   },
   "scripts": {
     "build": "tsc --noEmit",

package/src/actions.spec.ts

@@ -0,0 +1,29 @@
+import type { StoryContextForEnhancers } from "storybook/internal/types";
+import { expect, test } from "vitest";
+import { enhanceEventArgTypes } from "./actions";
+
+test("should enhance event arg types", () => {
+  const argTypes = {
+    someProp: {
+      name: "someProp",
+      table: { category: "props" },
+    },
+    click: {
+      name: "click",
+      table: { category: "events" },
+    },
+  } satisfies StoryContextForEnhancers["argTypes"];
+
+  const result = enhanceEventArgTypes({
+    argTypes,
+  } as unknown as StoryContextForEnhancers);
+
+  expect(result).toStrictEqual({
+    ...argTypes,
+    onClick: {
+      name: "onClick",
+      table: { disable: true },
+      action: "click",
+    },
+  });
+});

package/src/actions.ts

@@ -1,85 +1,97 @@
-import type { ArgTypes, Decorator, Meta } from "@storybook/vue3";
-import { deepmerge } from "deepmerge-ts";
+import type { Decorator } from "@storybook/vue3";
 import { useArgs } from "storybook/internal/preview-api";
-import { isReactive, reactive, watch } from "vue";
-import type { DefineStorybookActionsAndVModelsOptions, ExtractVueEventNames } from ".";
+import type { ArgTypes, ArgTypesEnhancer, StrictInputType } from "storybook/internal/types";
+import { isReactive, reactive, watch, type Events } from "vue";
+import { EVENT_DOC_MAP } from "./events";
 
 /**
- * Utility to define Storybook meta for a given Vue component which will take care of defining argTypes for
- * the given events as well as implementing v-model handlers so that the Storybook controls are updated when you interact with the component.
- * Should be preferred over manually defining argTypes for *.stories.ts files.
- *
- * @example
- * ```ts
- * // Input.stories.ts
- * import { defineStorybookActionsAndVModels } from '@sit-onyx/storybook-utils';
- * import type { Meta } from '@storybook/vue3';
- * import Input from './Input.vue';
- *
- * const meta: Meta<typeof Input> = {
- *   title: 'components/Input',
- *   ...defineStorybookActionsAndVModels({
- *     component: Input,
- *     events: ['update:modelValue', 'change'],
- *   }),
- * };
- * ```
+ * Adds actions for all argTypes of the 'event' category, so that they are logged via the actions plugin.
  */
-export const defineStorybookActionsAndVModels = <T>(
-  options: DefineStorybookActionsAndVModelsOptions<T>,
-): Meta => {
-  const defaultMeta = {
-    argTypes: {
-      ...defineActions(options.events),
-      ...{}, // this is needed to fix a type issue
-    },
-    decorators: [withVModelDecorator(options.events)],
-  } satisfies Meta;
-
-  return deepmerge(options, defaultMeta);
+export const enhanceEventArgTypes: ArgTypesEnhancer = ({ argTypes }) => {
+  Object.values(argTypes)
+    .filter(({ table }) => table?.category === "events")
+    .forEach(({ name }) => {
+      const eventName = `on${capitalizeFirstLetter(name)}`;
+      if (eventName in argTypes) {
+        return;
+      }
+      argTypes[eventName] = {
+        name: eventName,
+        table: { disable: true }, // do not add a second table entry for event name prefixed with "on"
+        action: name,
+      };
+    });
+  return argTypes;
 };
 
 /**
- * Defines Storybook actions ("argTypes") for the given events.
- * Reason for this wrapper function is that Storybook expects event names to be prefixed
- * with "on", e.g. "onClick".
+ * Allows logging and documentation for the passed event listener names in Storybook.
+ * Will be documented in a extra "Relevant HTML events" section in the Storybook documentation.
  *
- * However in Vue, the event names are plain like "click" instead of "onClick" because
- * otherwise we would use it like "@on-click="..."" which is redundant.
- *
- * So this utility will remove the on[eventName] entry from the Storybook panel/table
- * and register the correct eventName as action so it is logged in the "Actions" tab.
+ * @example
+ * ```typescript
+ * const meta: Meta<typeof OnyxButton> = {
+ *   title: "Buttons/Button",
+ *   component: OnyxButton,
+ *   argTypes: {
+ *     somethingElse: { ...someOtherArgType },
+ *     ...withNativeEventLogging(["onClick"]),
+ *  },
+ *};
+ * ```
  *
- * @example defineActions(["click", "input"])
+ * @param relevantEvents a list of event names that should be logged
+ * @returns Storybook ArgTypes object
  */
-export const defineActions = <T>(events: ExtractVueEventNames<T>[]): ArgTypes => {
-  return events.reduce<ArgTypes>((argTypes, eventName) => {
-    argTypes[`on${capitalizeFirstLetter(eventName)}`] = {
-      table: { disable: true },
-      action: eventName,
+export const withNativeEventLogging = (relevantEvents: (keyof Events)[]) =>
+  relevantEvents.reduce((argTypes, eventName) => {
+    const { constructor, event } = EVENT_DOC_MAP[eventName];
+    argTypes[eventName] = {
+      name: event.name,
+      control: false,
+      description: `The native HTML [${event.name}](${event.url}) event which dispatches an [${constructor.name}](${constructor.url}).`,
+      table: {
+        category: "Relevant HTML events",
+        type: { summary: constructor.name },
+      },
+      action: event.name,
     };
-
-    argTypes[eventName] = { control: false };
     return argTypes;
-  }, {});
+  }, {} as ArgTypes);
+
+export type WithVModelDecoratorOptions = {
+  /**
+   * The matcher for the v-model events.
+   * @default /^update:/
+   */
+  filter: (argType: StrictInputType) => boolean;
 };
 
 /**
- * Defines a custom decorator that will implement event handlers for all v-models
- * so that the Storybook controls are updated live when the user interacts with the component
+ * Defines a custom decorator that will implement event handlers for all v-models,
+ * so that the Storybook controls are updated live when the user interacts with the component.
+ * This ensures that the story and component props stay in sync.
  *
  * @example
  * ```ts
- * import Input from './Input.vue';
+ * // .storybook/preview.ts
  *
  * {
- *   decorators: [withVModelDecorator<typeof Input>(["update:modelValue"])]
+ *   decorators: [withVModelDecorator()]
  * }
  * ```
  */
-export const withVModelDecorator = <T>(events: ExtractVueEventNames<T>[]): Decorator => {
+
+export const withVModelDecorator = (options?: WithVModelDecoratorOptions): Decorator => {
   return (story, ctx) => {
-    const vModelEvents = events.filter((event) => event.startsWith("update:"));
+    const vModelFilter =
+      options?.filter ||
+      (({ table, name }) => table?.category === "events" && name.startsWith("update:"));
+
+    const vModelEvents = Object.values(ctx.argTypes)
+      .filter(vModelFilter)
+      .map(({ name }) => name);
+
     if (!vModelEvents.length) return story();
 
     const [args, updateArgs] = useArgs();