@sit-onyx/storybook-utils 1.0.0-alpha.111 → 1.0.0-alpha.112

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/storybook-utils",
   "description": "Storybook utilities for Vue",
-  "version": "1.0.0-alpha.111",
+  "version": "1.0.0-alpha.112",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -24,14 +24,16 @@
   },
   "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-dark-mode": ">= 4",
-    "sit-onyx": "^1.0.0-alpha.108"
+    "@sit-onyx/icons": "^0.1.0-alpha.1",
+    "sit-onyx": "^1.0.0-alpha.109"
   },
   "dependencies": {
-    "deepmerge-ts": "^7.0.0"
+    "deepmerge-ts": "^7.0.1"
   },
   "scripts": {
     "build": "tsc --noEmit",

package/src/preview.spec.ts

@@ -1,18 +1,31 @@
-import { describe, expect, test } from "vitest";
-import { sourceCodeTransformer } from "./preview";
+import bellRing from "@sit-onyx/icons/bell-ring.svg?raw";
+import calendar from "@sit-onyx/icons/calendar.svg?raw";
+import placeholder from "@sit-onyx/icons/placeholder.svg?raw";
+import { describe, expect, test, vi } from "vitest";
+import { replaceAll, sourceCodeTransformer } from "./preview";
+import * as sourceCodeGenerator from "./source-code-generator";
 
 describe("preview.ts", () => {
-  test("should transform source code", () => {
+  test("should transform source code and add icon imports", () => {
     // ARRANGE
-    // mix double and single quotes to test that both are supported
-    const originalSourceCode = `<OnyxTest v-on:test="someFunction" @empty='()=>({})' v-bind="{}" :disabled='true' :readonly="false" test="true" />`;
-
-    const expectedOutput = `<OnyxTest @test="someFunction" disabled :readonly="false" test />`;
+    const generatorSpy = vi.spyOn(sourceCodeGenerator, "generateSourceCode")
+      .mockReturnValue(`<template>
+<OnyxTest icon='${placeholder}' test='${bellRing}' :obj="{foo:'${replaceAll(calendar, '"', "\\'")}'}" />
+</template>`);
 
     // ACT
-    const output = sourceCodeTransformer(originalSourceCode);
+    const sourceCode = sourceCodeTransformer("", { title: "OnyxTest", args: {} });
 
     // ASSERT
-    expect(output).toBe(expectedOutput);
+    expect(generatorSpy).toHaveBeenCalledOnce();
+    expect(sourceCode).toBe(`<script lang="ts" setup>
+import bellRing from "@sit-onyx/icons/bell-ring.svg?raw";
+import calendar from "@sit-onyx/icons/calendar.svg?raw";
+import placeholder from "@sit-onyx/icons/placeholder.svg?raw";
+</script>
+
+<template>
+<OnyxTest :icon="placeholder" :test="bellRing" :obj="{foo:calendar}" />
+</template>`);
   });
 });

package/src/preview.ts

@@ -1,11 +1,13 @@
 import { DOCS_RENDERED } from "@storybook/core-events";
 import { addons } from "@storybook/preview-api";
 import { type ThemeVars } from "@storybook/theming";
-import { type Preview } from "@storybook/vue3";
+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 { requiredGlobalType, withRequired } from "./required";
+import { generateSourceCode } from "./source-code-generator";
 import { ONYX_BREAKPOINTS, createTheme } from "./theme";
 
 const themes = {
@@ -116,32 +118,68 @@ export const createPreview = <T extends Preview = Preview>(overrides?: T) => {
 };
 
 /**
- * Custom transformer for the story source code to better fit to our
- * Vue.js code because storybook per default does not render it exactly how
- * we want it to look.
+ * Custom transformer for the story source code to support improved source code generation.
+ * and add imports for all used onyx icons so icon imports are displayed in the source code
+ * instead of the the raw SVG content.
+ *
  * @see https://storybook.js.org/docs/react/api/doc-block-source
  */
-export const sourceCodeTransformer = (sourceCode: string): string => {
-  const replacements = [
-    // replace event bindings with shortcut
-    { searchValue: "v-on:", replaceValue: "@" },
-    // remove empty event handlers, e.g. @click="()=>({})" will be removed
-    { searchValue: / @\S*['"]\(\)=>\({}\)['"]/g, replaceValue: "" },
-    // // remove empty v-binds, e.g. v-bind="{}" will be removed
-    { searchValue: / v-bind=['"]{}['"]/g, replaceValue: "" },
-    // // replace boolean shortcuts for true, e.g. disabled="true" will be changed to just disabled
-    { searchValue: /:?(\S*)=['"]true['"]/g, replaceValue: "$1" },
-  ];
-
-  return replacements.reduce((code, replacement) => {
-    return replaceAll(code, replacement.searchValue, replacement.replaceValue);
-  }, sourceCode);
+export const sourceCodeTransformer = (
+  sourceCode: string,
+  ctx: Pick<StoryContext, "title" | "component" | "args">,
+): string => {
+  const RAW_ICONS = import.meta.glob("../node_modules/@sit-onyx/icons/src/assets/*.svg", {
+    query: "?raw",
+    import: "default",
+    eager: true,
+  });
+
+  /**
+   * Mapping between icon SVG content (key) and icon name (value).
+   * Needed to display a labelled dropdown list of all available icons.
+   */
+  const ALL_ICONS = Object.entries(RAW_ICONS).reduce<Record<string, string>>(
+    (obj, [filePath, content]) => {
+      obj[filePath.split("/").at(-1)!.replace(".svg", "")] = content as string;
+      return obj;
+    },
+    {},
+  );
+
+  let code = generateSourceCode(ctx);
+
+  const iconImports: string[] = [];
+
+  // add icon imports to the source code for all used onyx icons
+  Object.entries(ALL_ICONS).forEach(([iconName, iconContent]) => {
+    const importName = getIconImportName(iconName);
+    const singleQuotedIconContent = `'${replaceAll(iconContent, '"', "\\'")}'`;
+
+    if (code.includes(iconContent)) {
+      code = code.replace(new RegExp(` (\\S+)=['"]${iconContent}['"]`), ` :$1="${importName}"`);
+      iconImports.push(`import ${importName} from "@sit-onyx/icons/${iconName}.svg?raw";`);
+    } else if (code.includes(singleQuotedIconContent)) {
+      // support icons inside objects
+      code = code.replace(singleQuotedIconContent, importName);
+      iconImports.push(`import ${importName} from "@sit-onyx/icons/${iconName}.svg?raw";`);
+    }
+  });
+
+  if (iconImports.length > 0) {
+    return `<script lang="ts" setup>
+${iconImports.join("\n")}
+</script>
+
+${code}`;
+  }
+
+  return code;
 };
 
 /**
  * Custom String.replaceAll implementation using a RegExp
  * because String.replaceAll() is not available in our specified EcmaScript target in tsconfig.json
  */
-const replaceAll = (message: string, searchValue: string | RegExp, replaceValue: string) => {
-  return message.replace(new RegExp(searchValue, "gi"), replaceValue);
+export const replaceAll = (value: string, searchValue: string | RegExp, replaceValue: string) => {
+  return value.replace(new RegExp(searchValue, "gi"), replaceValue);
 };

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

@@ -0,0 +1,141 @@
+//
+// This file is only a temporary copy of the improved source code generation for Storybook.
+// It is intended to be deleted once its officially released in Storybook itself, see:
+// https://github.com/storybookjs/storybook/pull/27194
+//
+import { expect, test } from "vitest";
+import { h } from "vue";
+import {
+  extractSlotNames,
+  generatePropsSourceCode,
+  generateSlotSourceCode,
+} from "./source-code-generator";
+
+test("should generate source code for props", () => {
+  const slots = ["default", "testSlot"];
+
+  const code = generatePropsSourceCode(
+    {
+      a: "foo",
+      b: '"I am double quoted"',
+      c: 42,
+      d: true,
+      e: false,
+      f: [1, 2, 3],
+      g: {
+        g1: "foo",
+        b2: 42,
+      },
+      h: undefined,
+      i: null,
+      j: "",
+      k: BigInt(9007199254740991),
+      l: Symbol(),
+      m: Symbol("foo"),
+      default: "default slot",
+      testSlot: "test slot",
+    },
+    slots,
+  );
+
+  expect(code).toBe(
+    `a="foo" b='"I am double quoted"' :c="42" d :e="false" :f="[1,2,3]" :g="{'g1':'foo','b2':42}" :k="BigInt(9007199254740991)" :l="Symbol()" :m="Symbol('foo')"`,
+  );
+});
+
+test("should generate source code for slots", () => {
+  // slot code generator should support primitive values (string, number etc.)
+  // but also VNodes (e.g. created using h()) so custom Vue components can also be used
+  // inside slots with proper generated code
+
+  const slots = {
+    default: "default content",
+    a: "a content",
+    b: 42,
+    c: true,
+    // single VNode without props
+    d: h("div", "d content"),
+    // VNode with props and single child
+    e: h("div", { style: "color:red" }, "e content"),
+    // VNode with props and single child returned as getter
+    f: h("div", { style: "color:red" }, () => "f content"),
+    // VNode with multiple children
+    g: h("div", { style: "color:red" }, [
+      "child 1",
+      h("span", { style: "color:green" }, "child 2"),
+    ]),
+    // VNode multiple children but returned as getter
+    h: h("div", { style: "color:red" }, () => [
+      "child 1",
+      h("span", { style: "color:green" }, "child 2"),
+    ]),
+    // VNode with multiple and nested children
+    i: h("div", { style: "color:red" }, [
+      "child 1",
+      h("span", { style: "color:green" }, ["nested child 1", h("p", "nested child 2")]),
+    ]),
+    j: ["child 1", "child 2"],
+    k: null,
+    l: { foo: "bar" },
+    m: BigInt(9007199254740991),
+  };
+
+  const expectedCode = `default content
+
+<template #a>a content</template>
+
+<template #b>42</template>
+
+<template #c>true</template>
+
+<template #d><div>d content</div></template>
+
+<template #e><div style="color:red">e content</div></template>
+
+<template #f><div style="color:red">f content</div></template>
+
+<template #g><div style="color:red">child 1
+<span style="color:green">child 2</span></div></template>
+
+<template #h><div style="color:red">child 1
+<span style="color:green">child 2</span></div></template>
+
+<template #i><div style="color:red">child 1
+<span style="color:green">nested child 1
+<p>nested child 2</p></span></div></template>
+
+<template #j>child 1
+child 2</template>
+
+<template #l>{"foo":"bar"}</template>
+
+<template #m>{{ BigInt(9007199254740991) }}</template>`;
+
+  let actualCode = generateSlotSourceCode(slots, Object.keys(slots));
+  expect(actualCode).toBe(expectedCode);
+
+  // should generate the same code if getters/functions are used to return the slot content
+  const slotsWithGetters = Object.entries(slots).reduce<
+    Record<string, () => (typeof slots)[keyof typeof slots]>
+  >((obj, [slotName, value]) => {
+    obj[slotName] = () => value;
+    return obj;
+  }, {});
+
+  actualCode = generateSlotSourceCode(slotsWithGetters, Object.keys(slotsWithGetters));
+  expect(actualCode).toBe(expectedCode);
+});
+
+test.each([
+  { __docgenInfo: "invalid-value", slotNames: [] },
+  { __docgenInfo: {}, slotNames: [] },
+  { __docgenInfo: { slots: "invalid-value" }, slotNames: [] },
+  { __docgenInfo: { slots: ["invalid-value"] }, slotNames: [] },
+  {
+    __docgenInfo: { slots: [{ name: "slot-1" }, { name: "slot-2" }, { notName: "slot-3" }] },
+    slotNames: ["slot-1", "slot-2"],
+  },
+])("should extract slots names from __docgenInfo", ({ __docgenInfo, slotNames }) => {
+  const actualNames = extractSlotNames({ __docgenInfo });
+  expect(actualNames).toStrictEqual(slotNames);
+});

package/src/source-code-generator.ts

@@ -0,0 +1,277 @@
+//
+// This file is only a temporary copy of the improved source code generation for Storybook.
+// 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 type { VNode } from "vue";
+import { isVNode } from "vue";
+import { replaceAll } from "./preview";
+
+/**
+ * Generate Vue source code for the given Story.
+ * @returns Source code or empty string if source code could not be generated.
+ */
+export const generateSourceCode = (
+  ctx: Pick<StoryContext, "title" | "component" | "args">,
+): string => {
+  const componentName = ctx.component?.__name || ctx.title.split("/").at(-1)!;
+
+  const slotNames = extractSlotNames(ctx.component);
+  const slotSourceCode = generateSlotSourceCode(ctx.args, slotNames);
+  const propsSourceCode = generatePropsSourceCode(ctx.args, slotNames);
+
+  if (slotSourceCode) {
+    return `<template>
+    <${componentName} ${propsSourceCode}> ${slotSourceCode} </${componentName}>
+    </template>`;
+  }
+
+  // prefer self closing tag if no slot content exists
+  return `<template>
+  <${componentName} ${propsSourceCode} />
+  </template>`;
+};
+
+/**
+ * Checks if the source code generation should be skipped for the given Story context.
+ * Will be true if one of the following is true:
+ * - view mode is not "docs"
+ * - story is no arg story
+ * - story has set custom source code via parameters.docs.source.code
+ * - story has set source type to "code" via parameters.docs.source.type
+ */
+export const shouldSkipSourceCodeGeneration = (context: StoryContext): boolean => {
+  const sourceParams = context?.parameters.docs?.source;
+  if (sourceParams?.type === SourceType.DYNAMIC) {
+    // always render if the user forces it
+    return false;
+  }
+
+  const isArgsStory = context?.parameters.__isArgsStory;
+  const isDocsViewMode = context?.viewMode === "docs";
+
+  // never render if the user is forcing the block to render code, or
+  // if the user provides code, or if it's not an args story.
+  return (
+    !isDocsViewMode || !isArgsStory || sourceParams?.code || sourceParams?.type === SourceType.CODE
+  );
+};
+
+/**
+ * Gets all slot names from the `__docgenInfo` of the given component if available.
+ * Requires Storybook docs addon to be enabled.
+ * Default slot will always be sorted first, remaining slots are sorted alphabetically.
+ */
+export const extractSlotNames = (
+  component?: StoryContext["component"] & { __docgenInfo?: unknown },
+): string[] => {
+  if (!component || !("__docgenInfo" in component)) return [];
+
+  // type check __docgenInfo to prevent errors
+  if (!component.__docgenInfo || typeof component.__docgenInfo !== "object") return [];
+  if (
+    !("slots" in component.__docgenInfo) ||
+    !component.__docgenInfo.slots ||
+    !Array.isArray(component.__docgenInfo.slots)
+  ) {
+    return [];
+  }
+
+  return component.__docgenInfo.slots
+    .map((slot) => slot.name)
+    .filter((i): i is string => typeof i === "string")
+    .sort((a, b) => {
+      if (a === "default") return -1;
+      if (b === "default") return 1;
+      return a.localeCompare(b);
+    });
+};
+
+/**
+ * Generates the source code for the given Vue component properties.
+ *
+ * @param args Story args / property values.
+ * @param slotNames All slot names of the component. Needed to not generate code for args that are slots.
+ * Can be extracted using `extractSlotNames()`.
+ */
+export const generatePropsSourceCode = (
+  args: Record<string, unknown>,
+  slotNames: string[],
+): string => {
+  const props: string[] = [];
+
+  Object.entries(args).forEach(([propName, value]) => {
+    // ignore slots
+    if (slotNames.includes(propName)) return;
+
+    switch (typeof value) {
+      case "string":
+        if (value === "") return; // do not render empty strings
+
+        if (value.includes('"')) {
+          props.push(`${propName}='${value}'`);
+        } else {
+          props.push(`${propName}="${value}"`);
+        }
+
+        break;
+      case "number":
+        props.push(`:${propName}="${value}"`);
+        break;
+      case "bigint":
+        props.push(`:${propName}="BigInt(${value.toString()})"`);
+        break;
+      case "boolean":
+        props.push(value === true ? propName : `:${propName}="false"`);
+        break;
+      case "object":
+        if (value === null) return; // do not render null values
+        props.push(`:${propName}="${replaceAll(JSON.stringify(value), '"', "'")}"`);
+        break;
+      case "symbol": {
+        const symbol = `Symbol(${value.description ? `'${value.description}'` : ""})`;
+        props.push(`:${propName}="${symbol}"`);
+        break;
+      }
+      case "function":
+        // TODO: check if functions should be rendered in source code
+        break;
+    }
+  });
+
+  return props.join(" ");
+};
+
+/**
+ * Generates the source code for the given Vue component slots.
+ *
+ * @param args Story args.
+ * @param slotNames All slot names of the component. Needed to only generate slots and ignore props etc.
+ * Can be extracted using `extractSlotNames()`.
+ */
+export const generateSlotSourceCode = (args: Args, slotNames: string[]): string => {
+  /** List of slot source codes (e.g. <template #slotName>Content</template>) */
+  const slotSourceCodes: string[] = [];
+
+  slotNames.forEach((slotName) => {
+    const arg = args[slotName];
+    if (!arg) return;
+
+    const slotContent = generateSlotChildrenSourceCode([arg]);
+    if (!slotContent) return; // do not generate source code for empty slots
+
+    // TODO: support generating bindings
+    const bindings = "";
+
+    if (slotName === "default" && !bindings) {
+      // do not add unnecessary "<template #default>" tag since the default slot content without bindings
+      // can be put directly into the slot without need of "<template #default>"
+      slotSourceCodes.push(slotContent);
+    } else {
+      slotSourceCodes.push(`<template #${slotName}${bindings}>${slotContent}</template>`);
+    }
+  });
+
+  return slotSourceCodes.join("\n\n");
+};
+
+/**
+ * Generates the source code for the given slot children (the code inside <template #slotName></template>).
+ */
+const generateSlotChildrenSourceCode = (children: unknown[]): string => {
+  const slotChildrenSourceCodes: string[] = [];
+
+  /**
+   * Recursively generates the source code for a single slot child and all its children.
+   * @returns Source code for child and all nested children or empty string if child is of a non-supported type.
+   */
+  const generateSingleChildSourceCode = (child: unknown): string => {
+    if (isVNode(child)) {
+      return generateVNodeSourceCode(child);
+    }
+
+    switch (typeof child) {
+      case "string":
+      case "number":
+      case "boolean":
+        return child.toString();
+
+      case "object":
+        if (child === null) return "";
+        if (Array.isArray(child)) {
+          // if child also has children, we generate them recursively
+          return child
+            .map(generateSingleChildSourceCode)
+            .filter((code) => code !== "")
+            .join("\n");
+        }
+        return JSON.stringify(child);
+
+      case "function": {
+        const returnValue = child();
+        return generateSlotChildrenSourceCode([returnValue]);
+      }
+
+      case "bigint":
+        return `{{ BigInt(${child.toString()}) }}`;
+
+      // the only missing case here is "symbol"
+      // because rendering a symbol as slot / HTML does not make sense and is not supported by Vue
+      default:
+        return "";
+    }
+  };
+
+  children.forEach((child) => {
+    const sourceCode = generateSingleChildSourceCode(child);
+    if (sourceCode !== "") slotChildrenSourceCodes.push(sourceCode);
+  });
+
+  return slotChildrenSourceCodes.join("\n");
+};
+
+/**
+ * Generates source code for the given VNode and all its children (e.g. created using `h(MyComponent)` or `h("div")`).
+ */
+const generateVNodeSourceCode = (vnode: VNode): string => {
+  let componentName = "component";
+  if (typeof vnode.type === "string") {
+    // this is e.g. the case when rendering native HTML elements like, h("div")
+    componentName = vnode.type;
+  } else if (typeof vnode.type === "object" && "__name" in vnode.type) {
+    // this is the case when using custom Vue components like h(MyComponent)
+    if ("name" in vnode.type && vnode.type.name) {
+      // prefer custom component name set by the developer
+      componentName = vnode.type.name;
+    } else if ("__name" in vnode.type && vnode.type.__name) {
+      // otherwise use name inferred by Vue from the file name
+      componentName = vnode.type.__name;
+    }
+  }
+
+  let childrenCode = "";
+
+  if (typeof vnode.children === "string") {
+    childrenCode = vnode.children;
+  } else if (Array.isArray(vnode.children)) {
+    childrenCode = generateSlotChildrenSourceCode(vnode.children);
+  } else if (vnode.children) {
+    // children are an object, just like if regular Story args where used
+    // so we can generate the source code with the regular "generateSlotSourceCode()".
+    childrenCode = generateSlotSourceCode(
+      vnode.children,
+      // $stable is a default property in vnode.children so we need to filter it out
+      // to not generate source code for it
+      Object.keys(vnode.children).filter((i) => i !== "$stable"),
+    );
+  }
+
+  const props = vnode.props ? generatePropsSourceCode(vnode.props, []) : "";
+
+  // prefer self closing tag if no children exist
+  if (childrenCode)
+    return `<${componentName}${props ? ` ${props}` : ""}>${childrenCode}</${componentName}>`;
+  return `<${componentName}${props ? ` ${props}` : ""} />`;
+};