@sit-onyx/storybook-utils 1.0.0-beta.4 → 1.0.0-beta.41

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/storybook-utils",
   "description": "Storybook utilities for Vue",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.41",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -23,17 +23,14 @@
     "url": "https://github.com/SchwarzIT/onyx/issues"
   },
   "peerDependencies": {
-    "@storybook/core-events": ">= 8.0.0",
-    "@storybook/docs-tools": ">= 8.0.0",
-    "@storybook/preview-api": ">= 8.0.0",
-    "@storybook/theming": ">= 8.0.0",
-    "@storybook/vue3": ">= 8.0.0",
+    "@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.4"
+    "@sit-onyx/icons": "^1.0.0-beta.1",
+    "sit-onyx": "^1.0.0-beta.39"
   },
   "dependencies": {
-    "deepmerge-ts": "^7.0.3"
+    "deepmerge-ts": "^7.1.0"
   },
   "scripts": {
     "build": "tsc --noEmit",

package/src/actions.ts

@@ -1,85 +1,61 @@
-import { useArgs } from "@storybook/preview-api";
-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 type { ArgTypesEnhancer, StrictInputType } from "storybook/internal/types";
 import { isReactive, reactive, watch } from "vue";
-import type { DefineStorybookActionsAndVModelsOptions, ExtractVueEventNames } from ".";
 
 /**
- * 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 },
+        action: eventName,
+      };
+    });
+  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.
- *
- * 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 defineActions(["click", "input"])
- */
-export const defineActions = <T>(events: ExtractVueEventNames<T>[]): ArgTypes => {
-  return events.reduce<ArgTypes>((argTypes, eventName) => {
-    argTypes[`on${capitalizeFirstLetter(eventName)}`] = {
-      table: { disable: true },
-      action: eventName,
-    };
-
-    argTypes[eventName] = { control: false };
-    return 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();

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./actions";
 export * from "./preview";
+export * from "./sbType";
 export * from "./theme";
 export * from "./types";

package/src/preview.ts

@@ -1,11 +1,11 @@
-import { DOCS_RENDERED } from "@storybook/core-events";
-import { addons } from "@storybook/preview-api";
-import { type ThemeVars } from "@storybook/theming";
+import { getIconImportName } from "@sit-onyx/icons";
 import { type Preview, type StoryContext } from "@storybook/vue3";
 import { deepmerge } from "deepmerge-ts";
 import { DARK_MODE_EVENT_NAME } from "storybook-dark-mode";
-
-import { getIconImportName } from "@sit-onyx/icons";
+import { DOCS_RENDERED } from "storybook/internal/core-events";
+import { addons } from "storybook/internal/preview-api";
+import type { ThemeVars } from "storybook/internal/theming";
+import { enhanceEventArgTypes } from "./actions";
 import { requiredGlobalType, withRequired } from "./required";
 import { generateSourceCode } from "./source-code-generator";
 import { ONYX_BREAKPOINTS, createTheme } from "./theme";
@@ -22,6 +22,7 @@ const themes = {
  * - Setup for dark mode (including docs page). Requires addon `storybook-dark-mode` to be enabled in .storybook/main.ts file
  * - Custom Storybook theme using onyx colors (light and dark mode)
  * - Configure viewports / breakpoints as defined by onyx
+ * - Logs Vue emits as Storybook events
  *
  * @param overrides Custom preview / overrides, will be deep merged with the default preview.
  *
@@ -42,6 +43,7 @@ const themes = {
  */
 export const createPreview = <T extends Preview = Preview>(overrides?: T) => {
   const defaultPreview = {
+    argTypesEnhancers: [enhanceEventArgTypes],
     globalTypes: {
       ...requiredGlobalType,
     },
@@ -157,7 +159,10 @@ export const sourceCodeTransformer = (
     const escapedIconContent = `"${replaceAll(iconContent, '"', '\\"')}"`;
 
     if (code.includes(iconContent)) {
-      code = code.replace(new RegExp(` (\\S+)=['"]${iconContent}['"]`), ` :$1="${importName}"`);
+      code = code.replace(
+        new RegExp(` (\\S+)=['"]${escapeRegExp(iconContent)}['"]`),
+        ` :$1="${importName}"`,
+      );
       additionalImports.push(`import ${importName} from "@sit-onyx/icons/${iconName}.svg?raw";`);
     } else if (code.includes(singleQuotedIconContent)) {
       // support icons inside objects
@@ -207,3 +212,11 @@ ${code}`;
 export const replaceAll = (value: string, searchValue: string | RegExp, replaceValue: string) => {
   return value.replace(new RegExp(searchValue, "gi"), replaceValue);
 };
+
+/**
+ * Escapes the given string value to be used in `new RegExp()`.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#escaping
+ */
+export const escapeRegExp = (string: string) => {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+};

package/src/sbType.spec.ts

@@ -0,0 +1,38 @@
+import type { SBType } from "storybook/internal/types";
+import { describe, expect, test, vi } from "vitest";
+import { walkTree } from "./sbType";
+
+describe("walkTree", () => {
+  test.each<{ input: SBType; expected: SBType["name"][] }>([
+    { input: { name: "array", value: { name: "number" } }, expected: ["array", "number"] },
+    { input: { name: "object", value: { a: { name: "number" } } }, expected: ["object", "number"] },
+    { input: { name: "enum", value: ["a"] }, expected: ["enum"] },
+    {
+      input: { name: "intersection", value: [{ name: "number" }] },
+      expected: ["intersection", "number"],
+    },
+    { input: { name: "union", value: [{ name: "number" }] }, expected: ["union", "number"] },
+    { input: { name: "other", value: "a" }, expected: ["other"] },
+  ])("should execute cb for $input.name correctly", ({ input, expected }) => {
+    const spy = vi.fn<(p: SBType) => void>();
+    const result = walkTree(input, spy);
+
+    expect(result).toBeUndefined();
+    expect(spy).toHaveBeenCalledTimes(expected.length);
+    const nameCalls = spy.mock.calls.map(([{ name }]) => name);
+    expect(nameCalls).toMatchObject(expected);
+  });
+
+  test("should return value if there is any returned", () => {
+    const target: SBType = { name: "number", raw: "here" };
+    const overshoot: SBType = { name: "boolean", raw: "here" };
+    const parent: SBType = { name: "intersection", value: [target, overshoot] };
+    const returned = 42;
+    const spy = vi.fn((p: SBType) => (p.raw === "here" ? returned : undefined));
+    const result = walkTree({ name: "union", value: [parent] }, spy);
+
+    expect(spy).toHaveBeenCalledTimes(3);
+    expect(spy).toHaveBeenLastCalledWith(target, parent);
+    expect(result).toBe(returned);
+  });
+});

package/src/sbType.ts

@@ -0,0 +1,35 @@
+import type { SBType } from "storybook/internal/types";
+
+/**
+ * Call a function `cb` for every type node in the storybook type tree.
+ * @param inputType the root type
+ * @param cb the function that is called for every type. If any non-nullish value is returned by `cb` the execution is stopped and this value is returned.
+ * @param parent optional, the parent type. Is only used as input for the `cb` function and provided when recursing.
+ * @returns the first non-nullish value that is returned by `cb`
+ */
+export const walkTree = <TValue>(
+  inputType: SBType,
+  cb: (sb: SBType, parent?: SBType) => TValue,
+  parent?: SBType,
+): TValue | undefined => {
+  const shouldReturn = cb(inputType, parent);
+  if (shouldReturn) {
+    return shouldReturn;
+  }
+
+  if (inputType.name === "union" || inputType.name === "intersection") {
+    return inputType.value.reduce<TValue | undefined>(
+      (prev, it) => prev ?? walkTree(it, cb, inputType),
+      undefined,
+    );
+  }
+  if (inputType.name === "array") {
+    return walkTree(inputType.value, cb, inputType);
+  }
+  if (inputType.name === "object") {
+    return Object.values(inputType.value).reduce<TValue | undefined>(
+      (prev, it) => prev ?? walkTree(it, cb, inputType),
+      undefined,
+    );
+  }
+};

package/src/source-code-generator.spec.ts

@@ -156,16 +156,20 @@ test("should generate source code for slots with bindings", () => {
   type TestBindings = {
     foo: string;
     bar?: number;
+    boo: {
+      mimeType: string;
+    };
   };
 
   const slots = {
-    a: ({ foo, bar }: TestBindings) => `Slot with bindings ${foo} and ${bar}`,
-    b: ({ foo }: TestBindings) => h("a", { href: foo, target: foo }, `Test link: ${foo}`),
+    a: ({ foo, bar, boo }: TestBindings) => `Slot with bindings ${foo}, ${bar} and ${boo.mimeType}`,
+    b: ({ foo, boo }: TestBindings) =>
+      h("a", { href: foo, target: foo, type: boo.mimeType, ...boo }, `Test link: ${foo}`),
   };
 
-  const expectedCode = `<template #a="{ foo, bar }">Slot with bindings {{ foo }} and {{ bar }}</template>
+  const expectedCode = `<template #a="{ foo, bar, boo }">Slot with bindings {{ foo }}, {{ bar }} and {{ boo.mimeType }}</template>
 
-<template #b="{ foo }"><a :href="foo" :target="foo">Test link: {{ foo }}</a></template>`;
+<template #b="{ foo, boo }"><a :href="foo" :target="foo" :type="boo.mimeType" v-bind="boo">Test link: {{ foo }}</a></template>`;
 
   const actualCode = generateSlotSourceCode(slots, Object.keys(slots), {
     imports: {},

package/src/source-code-generator.ts

@@ -3,11 +3,25 @@
 // It is intended to be deleted once its officially released in Storybook itself, see:
 // https://github.com/storybookjs/storybook/pull/27194
 //
-import { SourceType } from "@storybook/docs-tools";
 import type { Args, StoryContext } from "@storybook/vue3";
+import { SourceType } from "storybook/internal/docs-tools";
 import { isVNode, type VNode } from "vue";
 import { replaceAll } from "./preview";
 
+/**
+ * Used to get the tracking data from the proxy.
+ * A symbol is unique, so when using it as a key it can't be accidentally accessed.
+ */
+const TRACKING_SYMBOL = Symbol("DEEP_ACCESS_SYMBOL");
+
+type TrackingProxy = {
+  [TRACKING_SYMBOL]: true;
+  toString: () => string;
+};
+
+const isProxy = (obj: unknown): obj is TrackingProxy =>
+  !!(obj && typeof obj === "object" && TRACKING_SYMBOL in obj);
+
 /**
  * Context that is passed down to nested components/slots when generating the source code for a single story.
  */
@@ -184,6 +198,10 @@ export const generatePropsSourceCode = (
     if (slotNames.includes(propName)) return;
     if (value == undefined) return; // do not render undefined/null values
 
+    if (isProxy(value)) {
+      value = value!.toString();
+    }
+
     switch (typeof value) {
       case "string":
         if (value === "") return; // do not render empty strings
@@ -225,7 +243,7 @@ export const generatePropsSourceCode = (
       case "object": {
         properties.push({
           name: propName,
-          value: formatObject(value),
+          value: formatObject(value ?? {}),
           // to follow Vue best practices, complex values like object and arrays are
           // usually placed inside the <script setup> block instead of inlining them in the <template>
           templateFn: undefined,
@@ -373,25 +391,60 @@ const generateSlotChildrenSourceCode = (
           (param) => !["{", "}"].includes(param),
         );
 
-        const parameters = paramNames.reduce<Record<string, string>>((obj, param) => {
-          obj[param] = `{{ ${param} }}`;
-          return obj;
-        }, {});
-
-        const returnValue = child(parameters);
-        let slotSourceCode = generateSlotChildrenSourceCode([returnValue], ctx);
-
-        // if slot bindings are used for properties of other components, our {{ paramName }} is incorrect because
-        // it would generate e.g. my-prop="{{ paramName }}", therefore, we replace it here to e.g. :my-prop="paramName"
+        // We create proxy to track how and which properties of a parameter are accessed
+        const parameters: Record<string, string> = {};
+        const proxied: Record<string, TrackingProxy> = {};
         paramNames.forEach((param) => {
-          slotSourceCode = replaceAll(
-            slotSourceCode,
-            new RegExp(` (\\S+)="{{ ${param} }}"`, "g"),
-            ` :$1="${param}"`,
+          parameters[param] = `{{ ${param} }}`;
+          // TODO: we should be able to extend the proxy logic here and maybe get rid of the `generatePropsSourceCode` code
+          proxied[param] = new Proxy(
+            {
+              // we use the symbol to identify the proxy
+              [TRACKING_SYMBOL]: true,
+            } as TrackingProxy,
+            {
+              // getter is called when any prop of the parameter is read
+              get: (t, key) => {
+                if (key === TRACKING_SYMBOL) {
+                  // allow retrieval of the tracking data
+                  return t[TRACKING_SYMBOL];
+                }
+                if ([Symbol.toPrimitive, Symbol.toStringTag, "toString"].includes(key)) {
+                  // when the parameter is used as a string we return the parameter name
+                  // we use the double brace notation as we don't know if the parameter is used in text or in a binding
+                  return () => `{{ ${param} }}`;
+                }
+                if (key === "v-bind") {
+                  // if this key is returned we just return the parameter name
+                  return `${param}`;
+                }
+                // otherwise a specific key of the parameter was accessed
+                // we use the double brace notation as we don't know if the parameter is used in text or in a binding
+                return `{{ ${param}.${key.toString()} }}`;
+              },
+              // ownKeys is called, among other uses, when an object is destructured
+              // in this case we assume the parameter is supposed to be bound using "v-bind"
+              // Therefore we only return one special key "v-bind" and the getter will be called afterwards with it
+              ownKeys: () => {
+                return [`v-bind`];
+              },
+              /** called when destructured */
+              getOwnPropertyDescriptor: () => ({
+                configurable: true,
+                enumerable: true,
+                value: param,
+                writable: true,
+              }),
+            },
           );
         });
 
-        return slotSourceCode;
+        const returnValue = child(proxied);
+        const slotSourceCode = generateSlotChildrenSourceCode([returnValue], ctx);
+
+        // if slot bindings are used for properties of other components, our {{ paramName }} is incorrect because
+        // it would generate e.g. my-prop="{{ paramName }}", therefore, we replace it here to e.g. :my-prop="paramName"
+        return replaceAll(slotSourceCode, / (\S+)="{{ (\S+) }}"/g, ` :$1="$2"`);
       }
 
       case "bigint":

package/src/theme.ts

@@ -1,7 +1,6 @@
-import type { ThemeVars, ThemeVarsPartial } from "@storybook/theming";
-import { create } from "@storybook/theming/create";
+import { ONYX_BREAKPOINTS as RAW_ONYX_BREAKPOINTS, type OnyxBreakpoint } from "sit-onyx";
 import onyxVariables from "sit-onyx/themes/onyx.json";
-import { ONYX_BREAKPOINTS as RAW_ONYX_BREAKPOINTS, type OnyxBreakpoint } from "sit-onyx/types";
+import { create, type ThemeVars, type ThemeVarsPartial } from "storybook/internal/theming";
 import onyxLogo from "./assets/logo-onyx.svg";
 
 /**

package/src/types.ts

@@ -1,52 +1,3 @@
-import type { ComponentPropsAndSlots, Meta } from "@storybook/vue3";
-
-/**
- * Extracts all event names defined by e.g. `defineEmits()` from the given Vue component.
- *
- * @example
- * ```ts
- * import Input from "./Input.vue";
- * type InputEvents = ExtractVueEventNames<typeof Input>; // e.g. "input" | "change"
- * ```
- */
-export type ExtractVueEventNames<VueComponent> =
-  Extract<
-    // extract all props/events of the vue component that are functions
-    ExtractKeysByValueType<
-      // this generic type will extract ALL props and events from the given Vue component
-      ComponentPropsAndSlots<VueComponent>,
-      // emits are declared as functions, so we only take props/events that are functions and ignore the rest
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- We must use any here to match the type defined by Vue
-      ((...args: any) => any) | undefined
-    >,
-    // filter out potential function properties by just picking events that start with "on"
-    `on${string}`
-  > extends `on${infer EventName}`
-    ? // until now the extracted event names still start with "on" but we want to have the plain event name
-      // so we will remove the "on" prefix and uncapitalized the first letter so e.g. "onClick" becomes "click"
-      Uncapitalize<EventName>
-    : never;
-
-/**
- * Extracts only the keys from T whose value type satisfies U.
- *
- * @example
- * ```ts
- * type Test = ExtractKeysByValueType<{ a: boolean, b: number, c: boolean }, boolean>
- * // result: "a" | "c"
- * ```
- */
-export type ExtractKeysByValueType<T, U> = { [P in keyof T]: T[P] extends U ? P : never }[keyof T] &
-  keyof T;
-
-/**
- * Options for defining Storybook actions and v-models.
- */
-export type DefineStorybookActionsAndVModelsOptions<T> = Meta<T> & {
-  component: NonNullable<T>;
-  events: ExtractVueEventNames<T>[];
-};
-
 export type StorybookGlobalType<TValue> = {
   name: string;
   description: string;
@@ -55,5 +6,6 @@ export type StorybookGlobalType<TValue> = {
     icon: string;
     items: { value: TValue; right?: string; title: string }[];
     title?: string;
+    dynamicTitle?: boolean;
   };
 };