Core: Add 'mapping' to support complex arg values

docs/writing-stories/args.md

@@ -122,6 +122,37 @@ The `args` param is always a set of `key:value` pairs delimited with a semicolon
 
 Args specified through the URL will extend and override any default values of args specified on the story.
 
+## Mapping to complex arg values
+
+Complex values such as JSX elements cannot be serialized to the manager (e.g. the Controls addon) or synced with the URL. To work around this limitation, arg values can be "mapped" from a simple string to a complex type using the `mapping` property in `argTypes`. This works on any type of arg, but makes most sense when used with the 'select' control.
+
+```
+argTypes: {
+  label: {
+    control: {
+      type: 'select',
+      options: ['Normal', 'Bold', 'Italic']
+    },
+    mapping: {
+      Bold: <b>Bold</b>,
+      Italic: <i>Italic</i>
+    }
+  }
+}
+```
+
+Note that `mapping` does not have to be exhaustive. If the arg value is not a property of `mapping`, the value will be used directly. Keys in `mapping` always correspond to arg *values*, even when `options` is an object. Specifying `options` as an object (key-value pairs) is useful if you want to use special characters in the input label. For example:
+
+```
+{
+  control: {
+    type: 'select',
+    options: { да: 'yes', нет: 'no' }
+  },
+  mapping: { yes: 'да', no: 'нет' }
+}
+```
+
 <details>
 <summary>Using args in addons</summary>
 

examples/official-storybook/stories/addon-controls.stories.tsx

@@ -5,10 +5,15 @@ export default {
   title: 'Addons/Controls',
   component: Button,
   argTypes: {
-    children: { control: 'text', name: 'Children' },
+    children: { control: 'text', name: 'Children', mapping: { basic: 'BASIC' } },
     type: { control: 'text', name: 'Type' },
     json: { control: 'object', name: 'JSON' },
     imageUrls: { control: { type: 'file', accept: '.png' }, name: 'Image Urls' },
+    label: {
+      name: 'Label',
+      control: { type: 'select', options: ['Plain', 'Bold'] },
+      mapping: { Bold: <b>Bold</b> },
+    },
   },
   parameters: { chromatic: { disable: true } },
 };
@@ -17,7 +22,7 @@ const DEFAULT_NESTED_OBJECT = { a: 4, b: { c: 'hello', d: [1, 2, 3] } };
 
 const Template = (args) => (
   <div>
-    <Button type={args.type}>{args.children}</Button>
+    <Button type={args.type}>{args.label || args.children}</Button>
     {args.json && <pre>{JSON.stringify(args.json, null, 2)}</pre>}
   </div>
 );

lib/client-api/src/story_store.ts

@@ -9,7 +9,7 @@ import deprecate from 'util-deprecate';
 
 import { Channel } from '@storybook/channels';
 import Events from '@storybook/core-events';
-import { logger } from '@storybook/client-logger';
+import { logger, once } from '@storybook/client-logger';
 import {
   Comparator,
   Parameters,
@@ -383,8 +383,32 @@ export default class StoryStore {
     const loaders = [...this._globalMetadata.loaders, ...kindMetadata.loaders, ...storyLoaders];
 
     const finalStoryFn = (context: StoryContext) => {
-      const { passArgsFirst = true } = context.parameters;
-      return passArgsFirst ? (original as ArgsStoryFn)(context.args, context) : original(context);
+      const { args, argTypes, parameters } = context;
+      if (
+        argTypes &&
+        Object.values(argTypes).some(({ control }) => {
+          if (!control?.options) return false;
+          return Object.values(control.options).some((v: any) => v && typeof v === 'object');
+        })
+      ) {
+        once.warn(
+          'Objects cannot be used as values in control options. Use a `mapping` instead.\n\nMore info: https://storybook.js.org/docs/react/writing-stories/args#mapping-to-complex-arg-values'
+        );
+      }
+
+      const { passArgsFirst = true } = parameters;
+      if (args) {
+        const mapped = {
+          ...context,
+          args: Object.entries(args).reduce((acc, [key, val]) => {
+            const { mapping } = argTypes?.[key] || {};
+            acc[key] = mapping && val in mapping ? mapping[val] : val;
+            return acc;
+          }, {} as Args),
+        };
+        return passArgsFirst ? (original as ArgsStoryFn)(mapped.args, mapped) : original(mapped);
+      }
+      return passArgsFirst ? (original as ArgsStoryFn)(args, context) : original(context);
     };
 
     // lazily decorate the story when it's loaded