0
# @storybook/docs-tools
1

2
@storybook/docs-tools provides shared utility functions that enable frameworks to implement comprehensive documentation features within Storybook. The package serves as a compatibility layer that re-exports core documentation tools from Storybook's internal infrastructure, handling argTypes enhancement, JSDoc parsing, type system conversion, and component introspection.
3

4
## Package Information
5

6
- **Package Name**: @storybook/docs-tools
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @storybook/docs-tools storybook`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  enhanceArgTypes, 
16
  hasDocsOrControls, 
17
  parseJsDoc,
18
  convert,
19
  extractComponentProps,
20
  createSummaryValue,
21
  ADDON_ID,
22
  SourceType,
23
  TypeSystem 
24
} from "@storybook/docs-tools";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  enhanceArgTypes, 
32
  hasDocsOrControls, 
33
  parseJsDoc,
34
  convert,
35
  extractComponentProps,
36
  createSummaryValue,
37
  ADDON_ID,
38
  SourceType,
39
  TypeSystem 
40
} = require("@storybook/docs-tools");
41
```
42

43
## Basic Usage
44

45
```typescript
46
import { enhanceArgTypes, parseJsDoc, convert, extractComponentProps, SourceType } from "@storybook/docs-tools";
47
import type { StoryContextForEnhancers } from "@storybook/core/types";
48

49
// Enhance argTypes for a story context
50
function myDecorator(story: any, context: StoryContextForEnhancers) {
51
  const enhancedArgTypes = enhanceArgTypes(context);
52
  
53
  // Parse JSDoc from component description
54
  const jsDocResult = parseJsDoc(context.component?.docgenInfo?.description);
55
  
56
  // Convert individual docgen info to Storybook format
57
  const docgenInfo = context.component?.__docgenInfo?.props?.someProp;
58
  if (docgenInfo) {
59
    const convertedType = convert(docgenInfo);
60
  }
61
  
62
  // Extract component properties
63
  const extractedProps = extractComponentProps(context.component, 'props');
64
  
65
  return story({ ...context, argTypes: enhancedArgTypes });
66
}
67

68
// Check if docs/controls are enabled
69
import type { Options } from "@storybook/core/types";
70

71
function configurePresets(options: Options) {
72
  if (hasDocsOrControls(options)) {
73
    // Configure documentation features
74
  }
75
}
76
```
77

78
## Architecture
79

80
@storybook/docs-tools is structured around several key subsystems:
81

82
- **ArgTypes Enhancement**: Combines extracted component metadata with user-defined argTypes
83
- **JSDoc Processing**: Parses and extracts structured information from JSDoc comments  
84
- **Type System Detection**: Identifies and handles JavaScript, Flow, and TypeScript type systems
85
- **Type Conversion**: Converts between different type representations (PropTypes, Flow, TypeScript)
86
- **Component Introspection**: Extracts properties, descriptions, and metadata from components
87
- **Documentation Generation**: Provides utilities for creating comprehensive component documentation
88

89
## Capabilities
90

91
### Core Constants and Configuration
92

93
Essential constants and enums for integrating with Storybook's documentation system.
94

95
```typescript { .api }
96
// Core addon identifiers
97
const ADDON_ID: "storybook/docs";
98
const PANEL_ID: string;
99
const PARAM_KEY: "docs";
100
const SNIPPET_RENDERED: string;
101

102
// Documentation source types
103
enum SourceType {
104
  AUTO = "auto",
105
  CODE = "code", 
106
  DYNAMIC = "dynamic"
107
}
108
```
109

110
[Constants and Configuration](./constants.md)
111

112
### ArgTypes Enhancement
113

114
Core functionality for enhancing component argTypes by combining extracted type information with user-provided definitions.
115

116
```typescript { .api }
117
function enhanceArgTypes<TRenderer extends Renderer>(
118
  context: StoryContextForEnhancers<TRenderer>
119
): typeof userArgTypes;
120

121
function hasDocsOrControls(options: Options): boolean;
122
```
123

124
[ArgTypes Enhancement](./argtypes-enhancement.md)
125

126
### JSDoc Parsing and Processing
127

128
Comprehensive JSDoc parsing system that extracts structured information from component documentation comments.
129

130
```typescript { .api }
131
function parseJsDoc(
132
  value: string | null, 
133
  options?: JsDocParsingOptions
134
): JsDocParsingResult;
135

136
interface JsDocParsingResult {
137
  includesJsDoc: boolean;
138
  ignore: boolean;
139
  description?: string;
140
  extractedTags?: ExtractedJsDoc;
141
}
142

143
interface ExtractedJsDoc {
144
  params?: ExtractedJsDocParam[] | null;
145
  deprecated?: string | null;
146
  returns?: ExtractedJsDocReturns | null;
147
  ignore: boolean;
148
}
149
```
150

151
[JSDoc Processing](./jsdoc-processing.md)
152

153
### Component Property Extraction
154

155
Tools for extracting and processing component properties from various docgen sources (react-docgen, vue-docgen-api, etc.).
156

157
```typescript { .api }
158
function extractComponentProps(
159
  component: Component, 
160
  section: string
161
): ExtractedProp[];
162

163
function extractComponentDescription(component?: Component): string;
164

165
interface ExtractedProp {
166
  propDef: PropDef;
167
  docgenInfo: DocgenInfo;
168
  jsDocTags?: ExtractedJsDoc;
169
  typeSystem: TypeSystem;
170
}
171
```
172

173
[Component Property Extraction](./component-extraction.md)
174

175
### Type System Conversion
176

177
Comprehensive type conversion system supporting PropTypes, Flow, and TypeScript type definitions.
178

179
```typescript { .api }
180
function convert(docgenInfo: DocgenInfo): any | null;
181

182
enum TypeSystem {
183
  JAVASCRIPT = "JavaScript",
184
  FLOW = "Flow", 
185
  TYPESCRIPT = "TypeScript",
186
  UNKNOWN = "Unknown"
187
}
188

189
interface DocgenInfo {
190
  type: DocgenPropType;
191
  flowType?: DocgenFlowType;
192
  tsType?: DocgenTypeScriptType;
193
  required: boolean;
194
  description: string;
195
  defaultValue: DocgenPropDefaultValue;
196
}
197
```
198

199
[Type System Conversion](./type-conversion.md)
200

201
### Utility Functions
202

203
Helper functions for string manipulation, value summarization, and type checking within the documentation system.
204

205
```typescript { .api }
206
function createSummaryValue(summary?: string, detail?: string): PropSummaryValue;
207
function isTooLongForTypeSummary(value: string): boolean;
208
function isTooLongForDefaultValueSummary(value: string): boolean;
209
function normalizeNewlines(string: string): string;
210

211
const MAX_TYPE_SUMMARY_LENGTH: 90;
212
const MAX_DEFAULT_VALUE_SUMMARY_LENGTH: 50;
213
```
214

215
[Utility Functions](./utilities.md)
216

217
## Types
218

219
```typescript { .api }
220
// Core component type
221
type Component = any;
222

223
// Type system detection
224
enum TypeSystem {
225
  JAVASCRIPT = "JavaScript",
226
  FLOW = "Flow", 
227
  TYPESCRIPT = "TypeScript",
228
  UNKNOWN = "Unknown"
229
}
230

231
// Property definition structures
232
interface PropDef {
233
  name: string;
234
  type: PropType | null;
235
  sbType?: any;
236
  required: boolean;
237
  description?: string;
238
  defaultValue?: PropDefaultValue | null;
239
  jsDocTags?: JsDocTags;
240
}
241

242
interface PropSummaryValue {
243
  summary?: string;
244
  detail?: string;
245
}
246

247
type PropType = PropSummaryValue;
248
type PropDefaultValue = PropSummaryValue;
249

250
// PropDef factory function type
251
type PropDefFactory = (
252
  propName: string,
253
  docgenInfo: DocgenInfo,
254
  jsDocTags?: ExtractedJsDoc
255
) => PropDef;
256

257
// JSDoc structures
258
interface JsDocParam {
259
  name: string | undefined | null;
260
  description?: string | null;
261
}
262

263
interface JsDocReturns {
264
  description?: string | null;
265
}
266

267
interface JsDocTags {
268
  params?: JsDocParam[] | null;
269
  returns?: JsDocReturns | null;
270
}
271

272
// Docgen type definitions
273
interface DocgenPropType {
274
  name: string;
275
  raw?: string;
276
  value?: any;
277
}
278

279
interface DocgenFlowType {
280
  name: string;
281
  raw?: string;
282
  elements?: DocgenFlowType[];
283
  signature?: any;
284
}
285

286
interface DocgenTypeScriptType {
287
  name: string;
288
  raw?: string;
289
  elements?: DocgenTypeScriptType[];
290
  signature?: any;
291
}
292

293
interface DocgenPropDefaultValue {
294
  value: string;
295
  computed: boolean;
296
}
297

298
// Extraction function types
299
type PropsExtractor = (component: Component) => { rows?: PropDef[] } | null;
300
type ArgTypesExtractor = (component: Component) => StrictArgTypes | null;
301
type ExtractProps = (component: Component, section: string) => ExtractedProp[];
302
```