chore: add relevant events logging (#1880)

A new Storybook Util `withNativeEventLoggingFor` is introduced.
It generates Storybook `ArgTypes` that allow us to document and log
relevant native events in Storybook.
These can be merged with other `ArgTypes`.
The native events will be documented in a new section "Relevant HTML
Events".

Relates to #1603

---------

Co-authored-by: Lars Rickert <[email protected]>

Author: JoCa96

.changeset/tender-zebras-flow.md

@@ -0,0 +1,5 @@
+---
+"@sit-onyx/storybook-utils": minor
+---
+
+feat: added withNativeEventLogging to log and document native events

apps/docs/playwright/snapshots/development-packages-storybook-utils-chromium-linux.png

@@ -154,3 +154,21 @@ export default preview;
 ```
 
 :::
+
+### withNativeEventLogging
+
+Allows logging and documentation for the passed native event listeners in Storybook.
+These will be documented in a extra "Relevant HTML events" section in the Storybook documentation.
+
+```ts [.storybook/preview.ts]
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
+
+const meta: Meta<typeof OnyxButton> = {
+  title: "Buttons/Button",
+  component: OnyxButton,
+  argTypes: {
+    somethingElse: { ...someOtherArgType },
+    ...withNativeEventLogging(["onClick"]),
+  },
+};
+```

apps/docs/playwright/snapshots/development-packages-storybook-utils-firefox-linux.png

@@ -1,4 +1,5 @@
 import checkSmall from "@sit-onyx/icons/check-small.svg?raw";
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import { defineIconSelectArgType } from "../../utils/storybook";
 import OnyxButton from "./OnyxButton.vue";
@@ -17,6 +18,7 @@ const meta: Meta<typeof OnyxButton> = {
   component: OnyxButton,
   argTypes: {
     icon: defineIconSelectArgType(),
+    ...withNativeEventLogging(["onClick"]),
   },
 };
 

apps/docs/playwright/snapshots/development-packages-storybook-utils-webkit-linux.png

@@ -1,4 +1,5 @@
 import trash from "@sit-onyx/icons/trash.svg?raw";
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import { h } from "vue";
 import { defineIconSelectArgType } from "../../utils/storybook";
@@ -13,6 +14,7 @@ const meta: Meta<typeof OnyxIconButton> = {
   argTypes: {
     icon: defineIconSelectArgType(),
     default: { control: { disable: true } },
+    ...withNativeEventLogging(["onClick"]),
   },
 };
 

apps/docs/src/development/packages/storybook-utils.md

@@ -1,3 +1,4 @@
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import OnyxInput from "./OnyxInput.vue";
 
@@ -16,6 +17,7 @@ const meta: Meta<typeof OnyxInput> = {
   ],
   argTypes: {
     pattern: { control: { type: "text" } },
+    ...withNativeEventLogging(["onInput", "onChange", "onFocusin", "onFocusout"]),
   },
 };
 

packages/sit-onyx/src/components/OnyxButton/OnyxButton.stories.ts

@@ -1,3 +1,4 @@
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import OnyxLink from "./OnyxLink.vue";
 
@@ -15,6 +16,7 @@ const meta: Meta<typeof OnyxLink> = {
       options: ["auto", true, false],
       control: { type: "radio" },
     },
+    ...withNativeEventLogging(["onClick"]),
   },
   decorators: [
     (story) => ({

packages/sit-onyx/src/components/OnyxIconButton/OnyxIconButton.stories.ts

@@ -1,3 +1,4 @@
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import OnyxNavAppArea from "./OnyxNavAppArea.vue";
 
@@ -9,6 +10,7 @@ const meta: Meta<typeof OnyxNavAppArea> = {
   component: OnyxNavAppArea,
   argTypes: {
     default: { control: { type: "text" } },
+    ...withNativeEventLogging(["onClick"]),
   },
 };
 

packages/sit-onyx/src/components/OnyxInput/OnyxInput.stories.ts

@@ -1,4 +1,5 @@
 import placeholder from "@sit-onyx/icons/placeholder.svg?raw";
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import { h } from "vue";
 import OnyxIcon from "../../../OnyxIcon/OnyxIcon.vue";
@@ -12,6 +13,7 @@ const meta: Meta<typeof OnyxMenuItem> = {
   component: OnyxMenuItem,
   argTypes: {
     default: { control: { type: "text" } },
+    ...withNativeEventLogging(["onClick"]),
   },
   decorators: [
     (story) => ({

packages/sit-onyx/src/components/OnyxLink/OnyxLink.stories.ts

@@ -1,3 +1,4 @@
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import OnyxRadioButton from "./OnyxRadioButton.vue";
 
@@ -7,6 +8,9 @@ import OnyxRadioButton from "./OnyxRadioButton.vue";
 const meta: Meta<typeof OnyxRadioButton> = {
   title: "Support/RadioButton",
   component: OnyxRadioButton,
+  argTypes: {
+    ...withNativeEventLogging(["onChange"]),
+  },
 };
 
 export default meta;

packages/sit-onyx/src/components/OnyxNavAppArea/OnyxNavAppArea.stories.ts

@@ -1,3 +1,4 @@
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import OnyxStepper from "./OnyxStepper.vue";
 
@@ -10,6 +11,9 @@ const meta: Meta<typeof OnyxStepper> = {
       template: `<div style="width: 16rem;"> <story /> </div>`,
     }),
   ],
+  argTypes: {
+    ...withNativeEventLogging(["onChange"]),
+  },
 };
 
 export default meta;

packages/sit-onyx/src/components/OnyxNavBar/modules/OnyxMenuItem/OnyxMenuItem.stories.ts

@@ -1,3 +1,4 @@
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import OnyxTextarea from "./OnyxTextarea.vue";
 
@@ -10,6 +11,9 @@ const meta: Meta<typeof OnyxTextarea> = {
       template: `<div style="max-width: 24rem;"> <story /> </div>`,
     }),
   ],
+  argTypes: {
+    ...withNativeEventLogging(["onChange"]),
+  },
 };
 
 export default meta;

packages/sit-onyx/src/components/OnyxRadioButton/OnyxRadioButton.stories.ts

@@ -1,3 +1,4 @@
+import { withNativeEventLogging } from "@sit-onyx/storybook-utils";
 import type { Meta, StoryObj } from "@storybook/vue3";
 import { defineIconSelectArgType } from "../../utils/storybook";
 import OnyxToastMessage from "./OnyxToastMessage.vue";
@@ -10,6 +11,7 @@ const meta: Meta<typeof OnyxToastMessage> = {
   component: OnyxToastMessage,
   argTypes: {
     icon: defineIconSelectArgType(),
+    ...withNativeEventLogging(["onClick"]),
   },
 };
 

packages/sit-onyx/src/components/OnyxStepper/OnyxStepper.stories.ts

@@ -1,7 +1,8 @@
 import type { Decorator } from "@storybook/vue3";
 import { useArgs } from "storybook/internal/preview-api";
-import type { ArgTypesEnhancer, StrictInputType } from "storybook/internal/types";
-import { isReactive, reactive, watch } from "vue";
+import type { ArgTypes, ArgTypesEnhancer, StrictInputType } from "storybook/internal/types";
+import { isReactive, reactive, watch, type Events } from "vue";
+import { EVENT_DOC_MAP } from "./events";
 
 /**
  * Adds actions for all argTypes of the 'event' category, so that they are logged via the actions plugin.
@@ -23,6 +24,41 @@ export const enhanceEventArgTypes: ArgTypesEnhancer = ({ argTypes }) => {
   return argTypes;
 };
 
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * const meta: Meta<typeof OnyxButton> = {
+ *   title: "Buttons/Button",
+ *   component: OnyxButton,
+ *   argTypes: {
+ *     somethingElse: { ...someOtherArgType },
+ *     ...withNativeEventLogging(["onClick"]),
+ *  },
+ *};
+ * ```
+ *
+ * @param relevantEvents a list of event names that should be logged
+ * @returns Storybook ArgTypes object
+ */
+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,
+    };
+    return argTypes;
+  }, {} as ArgTypes);
+
 export type WithVModelDecoratorOptions = {
   /**
    * The matcher for the v-model events.