@storybook/addon-controls 0.0.0-pr-23609-sha-f47ef339

package/README.md

@@ -0,0 +1,213 @@
+# Storybook Controls Addon
+
+[Storybook](https://storybook.js.org) Controls gives you a graphical UI to interact with a component's arguments dynamically, without needing to code. It creates an addon panel next to your component examples ("stories"), so you can edit them live.
+
+[Framework Support](https://storybook.js.org/docs/react/api/frameworks-feature-support)
+
+![Screenshot](https://raw.githubusercontent.com/storybookjs/storybook/next/code/addons/controls/docs/media/addon-controls-hero.gif)
+
+## Installation
+
+Controls is part of [essentials](https://storybook.js.org/docs/react/essentials/introduction) and so is installed in all new Storybooks by default. If you need to add it to your Storybook, you can run:
+
+```sh
+npm i -D @storybook/addon-controls
+```
+
+Then, add following content to [`.storybook/main.js`](https://storybook.js.org/docs/react/configure/overview#configure-your-storybook-project):
+
+```js
+export default {
+  addons: ['@storybook/addon-controls'],
+};
+```
+
+## Usage
+
+The usage is documented in the [documentation](https://storybook.js.org/docs/react/essentials/controls).
+
+## FAQs
+
+- [Storybook Controls Addon](#storybook-controls-addon)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [FAQs](#faqs)
+    - [How will this replace addon-knobs?](#how-will-this-replace-addon-knobs)
+    - [How do I migrate from addon-knobs?](#how-do-i-migrate-from-addon-knobs)
+    - [My controls aren't being auto-generated. What should I do?](#my-controls-arent-being-auto-generated-what-should-i-do)
+    - [How can I disable controls for certain fields on a particular story?](#how-can-i-disable-controls-for-certain-fields-on-a-particular-story)
+    - [How do controls work with MDX?](#how-do-controls-work-with-mdx)
+
+### How will this replace addon-knobs?
+
+Addon-knobs is one of Storybook's most popular addons with over 1M weekly downloads, so we know lots of users will be affected by this change. Knobs is also a mature addon, with various options that are not available in addon-controls.
+
+Therefore, rather than deprecating addon-knobs immediately, we will continue to release knobs with the Storybook core distribution until 7.0. This will give us time to improve Controls based on user feedback, and also give knobs users ample time to migrate.
+
+If you are somehow tied to knobs or prefer the knobs interface, we are happy to take on maintainers for the knobs project. If this interests you, hop on our [Discord](https://discord.gg/storybook).
+
+### How do I migrate from addon-knobs?
+
+If you're already using [Storybook Knobs](https://github.com/storybookjs/addon-knobs) you should consider migrating to Controls.
+
+You're probably using it for something that can be satisfied by one of the cases [described above](#writing-stories).
+
+Let's walk through two examples: migrating [knobs to auto-generated args](#knobs-to-custom-args) and [knobs to custom args](#knobs-to-custom-args).
+
+<h4>Knobs to auto-generated args</h4>
+
+First, let's consider a knobs version of a basic story that fills in the props for a component:
+
+```jsx
+import { text } from '@storybook/addon-knobs';
+import { Button } from './Button';
+
+export const Basic = () => <Button label={text('Label', 'hello')} />;
+```
+
+This fills in the Button's label based on a knob, which is exactly the [auto-generated](#auto-generated-args) use case above. So we can rewrite it using auto-generated args:
+
+```jsx
+export const Basic = (args) => <Button {...args} />;
+Basic.args = { label: 'hello' };
+```
+
+<h4>Knobs to manually-configured args</h4>
+
+Similarly, we can also consider a story that uses knob inputs to change its behavior:
+
+```jsx
+import { number, text } from '@storybook/addon-knobs';
+
+export const Reflow = () => {
+  const count = number('Count', 10, { min: 0, max: 100, range: true });
+  const label = text('Label', 'reflow');
+  return (
+    <>
+      {[...Array(count)].map((_, i) => (
+        <Button key={i} label={`button ${i}`} />
+      ))}
+    </>
+  );
+};
+```
+
+And again, as above, this can be rewritten using [fully custom args](https://storybook.js.org/docs/react/essentials/controls#fully-custom-args):
+
+```jsx
+export const Reflow = ({ count, label, ...args }) => (
+  <>
+    {[...Array(count)].map((_, i) => (
+      <Button key={i} label={`${label} ${i}`} {...args} />
+    ))}
+  </>
+);
+
+Reflow.args = {
+  count: 3,
+  label: 'reflow',
+};
+
+Reflow.argTypes = {
+  count: {
+    control: {
+      type: 'range',
+      min: 0,
+      max: 20,
+    },
+  },
+};
+```
+
+### My controls aren't being auto-generated. What should I do?
+
+There are a few known cases where controls can't be auto-generated:
+
+- You're using a framework for which automatic generation [isn't supported](https://storybook.js.org/docs/react/api/frameworks-feature-support)
+- You're trying to generate controls for a component defined in an external library
+
+With a little manual work you can still use controls in such cases. Consider the following example:
+
+```js
+import { Button } from 'some-external-library';
+
+export default {
+  title: 'Button',
+  argTypes: {
+    label: { control: 'text' },
+    borderWidth: { control: { type: 'number', min: 0, max: 10 } },
+  },
+};
+
+export const Basic = (args) => <Button {...args} />;
+
+Basic.args = {
+  label: 'hello',
+  borderWidth: 1,
+};
+```
+
+The `argTypes` annotation (which can also be applied to individual stories if needed), gives Storybook the hints it needs to generate controls in these unsupported cases. See [control annotations](https://storybook.js.org/docs/react/essentials/controls#annotation) for a full list of control types.
+
+It's also possible that your Storybook is misconfigured. If you think this might be the case, please search through Storybook's [Github issues](https://github.com/storybookjs/storybook/issues), and file a new issue if you don't find one that matches your use case.
+
+### How can I disable controls for certain fields on a particular story?
+
+The `argTypes` annotation can be used to hide controls for a particular row, or even hide rows.
+
+Suppose you have a `Button` component with `borderWidth` and `label` properties (auto-generated or otherwise) and you want to hide the `borderWidth` row completely and disable controls for the `label` row on a specific story. Here's how you'd do that:
+
+```js
+import { Button } from 'button';
+
+export default {
+  title: 'Button',
+  component: Button,
+};
+
+export const CustomControls = (args) => <Button {...args} />;
+CustomControls.argTypes = {
+  borderWidth: { table: { disable: true } },
+  label: { control: { disable: true } },
+};
+```
+
+Like [story parameters](https://storybook.js.org/docs/react/writing-stories/parameters), `args` and `argTypes` annotations are hierarchically merged, so story-level annotations overwrite component-level annotations.
+
+### How do controls work with MDX?
+
+MDX compiles to component story format (CSF) under the hood, so there's a direct mapping for every example above using the `args` and `argTypes` props.
+
+Consider this example in CSF:
+
+```js
+import { Button } from './Button';
+export default {
+  title: 'Button',
+  component: Button,
+  argTypes: {
+    background: { control: 'color' },
+  },
+};
+
+const Template = (args) => <Button {...args} />;
+export const Basic = Template.bind({});
+Basic.args = { label: 'hello', background: '#ff0' };
+```
+
+Here's the MDX equivalent:
+
+```jsx
+import { Meta, Story } from '@storybook/addon-docs';
+import { Button } from './Button';
+
+<Meta title="Button" component={Button} argTypes={{ background: { control: 'color' } }} />
+
+export const Template = (args) => <Button {...args} />
+
+<Story name="Basic" args={{ label: 'hello', background: '#ff0' }}>
+  {Template.bind({})}
+</Story>
+```
+
+For more info, see a full [Controls example in MDX for Vue](https://raw.githubusercontent.com/storybookjs/storybook/next/code/examples/vue-kitchen-sink/src/stories/addon-controls.stories.mdx).

package/dist/chunk-I36WBKUI.mjs

@@ -0,0 +1,3 @@
+var ADDON_ID="addon-controls",PARAM_KEY="controls";
+
+export { ADDON_ID, PARAM_KEY };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare const PARAM_KEY: "controls";
+
+export { PARAM_KEY };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:!0})},__copyProps=(to,from,except,desc)=>{if(from&&typeof from=="object"||typeof from=="function")for(let key of __getOwnPropNames(from))!__hasOwnProp.call(to,key)&&key!==except&&__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to};var __toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:!0}),mod);var src_exports={};__export(src_exports,{PARAM_KEY:()=>PARAM_KEY});module.exports=__toCommonJS(src_exports);var PARAM_KEY="controls";0&&(module.exports={PARAM_KEY});

package/dist/index.mjs

@@ -0,0 +1 @@
+export { PARAM_KEY } from './chunk-I36WBKUI.mjs';

package/dist/manager.d.ts

@@ -0,0 +1,2 @@
+
+export { }

package/dist/manager.js

@@ -0,0 +1 @@
+"use strict";var __create=Object.create;var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __getProtoOf=Object.getPrototypeOf,__hasOwnProp=Object.prototype.hasOwnProperty;var __copyProps=(to,from,except,desc)=>{if(from&&typeof from=="object"||typeof from=="function")for(let key of __getOwnPropNames(from))!__hasOwnProp.call(to,key)&&key!==except&&__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to};var __toESM=(mod,isNodeMode,target)=>(target=mod!=null?__create(__getProtoOf(mod)):{},__copyProps(isNodeMode||!mod||!mod.__esModule?__defProp(target,"default",{value:mod,enumerable:!0}):target,mod));var import_react2=__toESM(require("react")),import_manager_api2=require("@storybook/manager-api"),import_components=require("@storybook/components");var import_react=__toESM(require("react")),import_manager_api=require("@storybook/manager-api"),import_blocks=require("@storybook/blocks");var ADDON_ID="addon-controls",PARAM_KEY="controls";var ControlsPanel=()=>{let[args,updateArgs,resetArgs]=(0,import_manager_api.useArgs)(),[globals]=(0,import_manager_api.useGlobals)(),rows=(0,import_manager_api.useArgTypes)(),isArgsStory=(0,import_manager_api.useParameter)("__isArgsStory",!1),{expanded,sort,presetColors,hideNoControlsWarning=!1}=(0,import_manager_api.useParameter)(PARAM_KEY,{}),{path}=(0,import_manager_api.useStorybookState)(),hasControls=Object.values(rows).some(arg=>arg==null?void 0:arg.control),showWarning=!(hasControls&&isArgsStory)&&!hideNoControlsWarning,withPresetColors=Object.entries(rows).reduce((acc,[key,arg])=>{var _a,_b;return((_a=arg==null?void 0:arg.control)==null?void 0:_a.type)!=="color"||(_b=arg==null?void 0:arg.control)!=null&&_b.presetColors?acc[key]=arg:acc[key]={...arg,control:{...arg.control,presetColors}},acc},{});return import_react.default.createElement(import_react.default.Fragment,null,showWarning&&import_react.default.createElement(import_blocks.NoControlsWarning,null),import_react.default.createElement(import_blocks.PureArgsTable,{key:path,compact:!expanded&&hasControls,rows:withPresetColors,args,globals,updateArgs,resetArgs,inAddonPanel:!0,sort}))};function Title(){let rows=(0,import_manager_api2.useArgTypes)(),controlsCount=Object.values(rows).filter(argType=>{var _a;return(argType==null?void 0:argType.control)&&!((_a=argType==null?void 0:argType.table)!=null&&_a.disable)}).length;return import_react2.default.createElement("div",null,import_react2.default.createElement(import_components.Spaced,{col:1},import_react2.default.createElement("span",{style:{display:"inline-block",verticalAlign:"middle"}},"Controls"),controlsCount===0?"":import_react2.default.createElement(import_components.Badge,{status:"neutral"},controlsCount)))}import_manager_api2.addons.register(ADDON_ID,api=>{import_manager_api2.addons.add(ADDON_ID,{title:Title,type:import_manager_api2.types.PANEL,paramKey:PARAM_KEY,render:({active})=>!active||!api.getCurrentStoryData()?null:import_react2.default.createElement(import_components.AddonPanel,{active},import_react2.default.createElement(ControlsPanel,null))})});

package/dist/manager.mjs

@@ -0,0 +1,7 @@
+import { ADDON_ID, PARAM_KEY } from './chunk-I36WBKUI.mjs';
+import React2 from 'react';
+import { addons, types, useArgs, useGlobals, useArgTypes, useParameter, useStorybookState } from '@storybook/manager-api';
+import { AddonPanel, Spaced, Badge } from '@storybook/components';
+import { NoControlsWarning, PureArgsTable } from '@storybook/blocks';
+
+var ControlsPanel=()=>{let[args,updateArgs,resetArgs]=useArgs(),[globals]=useGlobals(),rows=useArgTypes(),isArgsStory=useParameter("__isArgsStory",!1),{expanded,sort,presetColors,hideNoControlsWarning=!1}=useParameter(PARAM_KEY,{}),{path}=useStorybookState(),hasControls=Object.values(rows).some(arg=>arg?.control),showWarning=!(hasControls&&isArgsStory)&&!hideNoControlsWarning,withPresetColors=Object.entries(rows).reduce((acc,[key,arg])=>(arg?.control?.type!=="color"||arg?.control?.presetColors?acc[key]=arg:acc[key]={...arg,control:{...arg.control,presetColors}},acc),{});return React2.createElement(React2.Fragment,null,showWarning&&React2.createElement(NoControlsWarning,null),React2.createElement(PureArgsTable,{key:path,compact:!expanded&&hasControls,rows:withPresetColors,args,globals,updateArgs,resetArgs,inAddonPanel:!0,sort}))};function Title(){let rows=useArgTypes(),controlsCount=Object.values(rows).filter(argType=>argType?.control&&!argType?.table?.disable).length;return React2.createElement("div",null,React2.createElement(Spaced,{col:1},React2.createElement("span",{style:{display:"inline-block",verticalAlign:"middle"}},"Controls"),controlsCount===0?"":React2.createElement(Badge,{status:"neutral"},controlsCount)))}addons.register(ADDON_ID,api=>{addons.add(ADDON_ID,{title:Title,type:types.PANEL,paramKey:PARAM_KEY,render:({active})=>!active||!api.getCurrentStoryData()?null:React2.createElement(AddonPanel,{active},React2.createElement(ControlsPanel,null))});});

package/jest.config.js

@@ -0,0 +1,7 @@
+const path = require('path');
+const baseConfig = require('../../jest.config.browser');
+
+module.exports = {
+  ...baseConfig,
+  displayName: __dirname.split(path.sep).slice(-2).join(path.posix.sep),
+};

package/manager.js

@@ -0,0 +1 @@
+import './dist/manager';

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@storybook/addon-controls",
+  "version": "0.0.0-pr-23609-sha-f47ef339",
+  "description": "Interact with component inputs dynamically in the Storybook UI",
+  "keywords": [
+    "addon",
+    "storybook",
+    "knobs",
+    "controls",
+    "properties",
+    "essentials",
+    "data-state"
+  ],
+  "homepage": "https://github.com/storybookjs/storybook/tree/next/code/addons/controls",
+  "bugs": {
+    "url": "https://github.com/storybookjs/storybook/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/storybookjs/storybook.git",
+    "directory": "code/addons/controls"
+  },
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/storybook"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    },
+    "./manager": {
+      "types": "./dist/manager.d.ts",
+      "require": "./dist/manager.js",
+      "import": "./dist/manager.mjs"
+    },
+    "./register": {
+      "types": "./dist/manager.d.ts",
+      "require": "./dist/manager.js",
+      "import": "./dist/manager.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "dist/index.d.ts"
+      ],
+      "manager": [
+        "dist/manager.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "*.js",
+    "*.d.ts"
+  ],
+  "scripts": {
+    "check": "../../../scripts/prepare/check.ts",
+    "prep": "../../../scripts/prepare/bundle.ts"
+  },
+  "dependencies": {
+    "@storybook/blocks": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/client-logger": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/components": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/core-common": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/manager-api": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/node-logger": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/preview-api": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/theming": "0.0.0-pr-23609-sha-f47ef339",
+    "@storybook/types": "0.0.0-pr-23609-sha-f47ef339",
+    "lodash": "^4.17.21",
+    "ts-dedent": "^2.0.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bundler": {
+    "entries": [
+      "./src/index.ts",
+      "./src/manager.tsx"
+    ],
+    "platform": "browser"
+  },
+  "gitHead": "e6a7fd8a655c69780bc20b9749c2699e44beae17",
+  "storybook": {
+    "displayName": "Controls",
+    "icon": "https://user-images.githubusercontent.com/263385/101991669-479cc600-3c7c-11eb-93d9-38b67e8371f2.png",
+    "supportedFrameworks": [
+      "react",
+      "vue",
+      "angular",
+      "web-components",
+      "ember"
+    ]
+  }
+}