@sit-onyx/storybook-utils 1.0.0-beta.9 → 1.0.0-beta.90

package/README.md

@@ -1,9 +1,5 @@
 <div align="center" style="text-align: center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-light.svg">
-    <source media="(prefers-color-scheme: light)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg">
-    <img alt="onyx logo" src="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg" width="160px">
-  </picture>
+  <img alt="onyx logo" src="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo.svg" height="96px">
 </div>
 
 <br>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/storybook-utils",
   "description": "Storybook utilities for Vue",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.0-beta.90",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -11,7 +11,7 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./style.css": "./src/index.css"
+    "./style.css": "./src/style.css"
   },
   "homepage": "https://onyx.schwarz/development/packages/storybook-utils.html",
   "repository": {
@@ -23,18 +23,27 @@
     "url": "https://github.com/SchwarzIT/onyx/issues"
   },
   "peerDependencies": {
-    "@storybook/vue3": ">= 8.2.0",
-    "storybook": ">= 8.2.0",
-    "storybook-dark-mode": ">= 4",
-    "@sit-onyx/icons": "^1.0.0-beta.0",
-    "sit-onyx": "^1.0.0-beta.8"
+    "@storybook/vue3": ">= 9.0.0",
+    "@vueless/storybook-dark-mode": ">= 9.0.0",
+    "storybook": ">= 9.0.0",
+    "vue-component-type-helpers": ">= 2",
+    "@sit-onyx/icons": "^1.0.0-beta.18",
+    "@sit-onyx/shared": "^1.0.0-beta.3"
   },
   "dependencies": {
-    "deepmerge-ts": "^7.0.3"
+    "deepmerge-ts": "^7.1.5"
+  },
+  "devDependencies": {
+    "storybook": "^9.0.12",
+    "vue": "3.5.16",
+    "vue-component-type-helpers": "^2.2.10",
+    "@sit-onyx/icons": "^1.0.0-beta.18",
+    "@sit-onyx/shared": "^1.0.0-beta.3"
   },
   "scripts": {
     "build": "tsc --noEmit",
     "test": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "stylelint": "stylelint \"src/**/*.css\""
   }
 }

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,144 @@
-import type { ArgTypes, Decorator, Meta } from "@storybook/vue3";
-import { deepmerge } from "deepmerge-ts";
+import type { Decorator } from "@storybook/vue3";
+import { action } from "storybook/actions";
 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 { h, isReactive, reactive, watch, type Component, type Events } from "vue";
+import type { ComponentProps, ComponentSlots } from "vue-component-type-helpers";
+import { EVENT_DOC_MAP } from "./events";
+
+type ComponentEmits<Props extends ComponentProps<unknown>> = keyof {
+  [Key in keyof Props as Key extends `on${string}` ? Key : never]: true;
+};
 
 /**
- * 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.
+ * Wraps the original component and adds [Storybook action logging](https://storybook.js.org/docs/essentials/actions).
+ * This is useful for slotted child components that emit relevant events.
+ *
+ * Returns a wrapped component, which can be used in place of the original component.
  *
- * @example
  * ```ts
- * // Input.stories.ts
- * import { defineStorybookActionsAndVModels } from '@sit-onyx/storybook-utils';
- * import type { Meta } from '@storybook/vue3';
- * import Input from './Input.vue';
+ * import { createActionLoggerWrapper } from "@sit-onyx/storybook-utils";
+ * import _ChildComponent from "./_ChildComponent.vue";
+ *
+ * // Usual story setup...
  *
- * const meta: Meta<typeof Input> = {
- *   title: 'components/Input',
- *   ...defineStorybookActionsAndVModels({
- *     component: Input,
- *     events: ['update:modelValue', 'change'],
- *   }),
- * };
+ * const ChildComponent = createActionLoggerWrapper(_ChildComponent, ["onChildEmit"]);
+ *
+ * export const Default = {
+ *   args: {
+ *   propName: 'Value'
+ *     someSlot: () => h(ChildComponent, { label: "Item 1" }),
+ *   },
+ * } satisfies Story;
  * ```
  */
-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 createActionLoggerWrapper =
+  <C extends Component>(component: C, emitsToLog: ComponentEmits<ComponentProps<C>>[]) =>
+  (props: ComponentProps<C>, ctx: { slots: ComponentSlots<C> }) => {
+    const entries = emitsToLog.map((emitName) => [
+      emitName,
+      // Log action in the format of `<component name> ~ <emit name>`
+      action(`${(component as { __name: string }).__name} ~ ${String(emitName)}`),
+    ]);
+    const eventHandler = Object.fromEntries(entries);
+    return h(
+      component,
+      {
+        ...eventHandler,
+        ...props,
+      },
+      ctx.slots,
+    );
+  };
+
+/**
+ * Adds actions for all argTypes of the 'event' category, so that they are logged via the actions plugin.
+ */
+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".
- *
- * 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.
+ * 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.
  *
- * 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, index: number, array: 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();