docs.d.ts 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435
  1. /**
  2. * This is an autogenerated file created by the Stencil compiler.
  3. * DO NOT MODIFY IT MANUALLY
  4. */
  5. interface ComponentCompilerPropertyComplexType {
  6. /**
  7. * The string of the original type annotation in the Stencil source code
  8. */
  9. original: string;
  10. /**
  11. * A 'resolved' type, where e.g. imported types have been resolved and inlined
  12. *
  13. * For instance, an annotation like `(foo: Foo) => string;` will be
  14. * converted to `(foo: { foo: string }) => string;`.
  15. */
  16. resolved: string;
  17. /**
  18. * A record of the types which were referenced in the assorted type
  19. * annotation in the original source file.
  20. */
  21. references: ComponentCompilerTypeReferences;
  22. }
  23. type ComponentCompilerTypeReferences = Record<string, ComponentCompilerTypeReference>;
  24. interface ComponentCompilerTypeReference {
  25. /**
  26. * A type may be defined:
  27. * - locally (in the same file as the component that uses it)
  28. * - globally
  29. * - by importing it into a file (and is defined elsewhere)
  30. */
  31. location: "local" | "global" | "import";
  32. /**
  33. * The path to the type reference, if applicable (global types should not need a path associated with them)
  34. */
  35. path?: string;
  36. /**
  37. * An ID for this type which is unique within a Stencil project.
  38. */
  39. id: string;
  40. }
  41. interface ComponentCompilerReferencedType {
  42. /**
  43. * The path to the module where the type is declared.
  44. */
  45. path: string;
  46. /**
  47. * The string of the original type annotation in the Stencil source code
  48. */
  49. declaration: string;
  50. /**
  51. * An extracted docstring
  52. */
  53. docstring: string;
  54. }
  55. interface ComponentCompilerEventComplexType {
  56. original: string;
  57. resolved: string;
  58. references: ComponentCompilerTypeReferences;
  59. }
  60. interface ComponentCompilerMethodComplexType {
  61. signature: string;
  62. parameters: JsonDocMethodParameter[];
  63. references: ComponentCompilerTypeReferences;
  64. return: string;
  65. }
  66. /**
  67. * The Type Library holds information about the types which are used in a
  68. * Stencil project. During compilation, Stencil gathers information about the
  69. * types which form part of a component's public API, such as properties
  70. * decorated with `@Prop`, `@Event`, `@Watch`, etc. This type information is
  71. * then added to the Type Library, where it can be accessed later on for
  72. * generating documentation.
  73. *
  74. * This information is included in the file written by the `docs-json` output
  75. * target (see {@link JsonDocs.typeLibrary}).
  76. */
  77. export type JsonDocsTypeLibrary = Record<string, ComponentCompilerReferencedType>;
  78. /**
  79. * A container for JSDoc metadata for a project
  80. */
  81. export interface JsonDocs {
  82. /**
  83. * The metadata for the JSDocs for each component in a Stencil project
  84. */
  85. components: JsonDocsComponent[];
  86. /**
  87. * The timestamp at which the metadata was generated, in the format YYYY-MM-DDThh:mm:ss
  88. */
  89. timestamp: string;
  90. compiler: {
  91. /**
  92. * The name of the compiler that generated the metadata
  93. */
  94. name: string;
  95. /**
  96. * The version of the Stencil compiler that generated the metadata
  97. */
  98. version: string;
  99. /**
  100. * The version of TypeScript that was used to generate the metadata
  101. */
  102. typescriptVersion: string;
  103. };
  104. typeLibrary: JsonDocsTypeLibrary;
  105. }
  106. /**
  107. * Container for JSDoc metadata for a single Stencil component
  108. */
  109. export interface JsonDocsComponent {
  110. /**
  111. * The directory containing the Stencil component, minus the file name.
  112. *
  113. * @example /workspaces/stencil-project/src/components/my-component
  114. */
  115. dirPath?: string;
  116. /**
  117. * The name of the file containing the Stencil component, with no path
  118. *
  119. * @example my-component.tsx
  120. */
  121. fileName?: string;
  122. /**
  123. * The full path of the file containing the Stencil component
  124. *
  125. * @example /workspaces/stencil-project/src/components/my-component/my-component.tsx
  126. */
  127. filePath?: string;
  128. /**
  129. * The path to the component's `readme.md` file, including the filename
  130. *
  131. * @example /workspaces/stencil-project/src/components/my-component/readme.md
  132. */
  133. readmePath?: string;
  134. /**
  135. * The path to the component's `usage` directory
  136. *
  137. * @example /workspaces/stencil-project/src/components/my-component/usage/
  138. */
  139. usagesDir?: string;
  140. /**
  141. * The encapsulation strategy for a component
  142. */
  143. encapsulation: "shadow" | "scoped" | "none";
  144. /**
  145. * The tag name for the component, for use in HTML
  146. */
  147. tag: string;
  148. /**
  149. * The contents of a component's `readme.md` that are user generated.
  150. *
  151. * Auto-generated contents are not stored in this reference.
  152. */
  153. readme: string;
  154. /**
  155. * The description of a Stencil component, found in the JSDoc that sits above the component's declaration
  156. */
  157. docs: string;
  158. /**
  159. * JSDoc tags found in the JSDoc comment written atop a component's declaration
  160. */
  161. docsTags: JsonDocsTag[];
  162. /**
  163. * The text from the class-level JSDoc for a Stencil component, if present.
  164. */
  165. overview?: string;
  166. /**
  167. * A mapping of usage example file names to their contents for the component.
  168. */
  169. usage: JsonDocsUsage;
  170. /**
  171. * Array of metadata for a component's `@Prop`s
  172. */
  173. props: JsonDocsProp[];
  174. /**
  175. * Array of metadata for a component's `@Method`s
  176. */
  177. methods: JsonDocsMethod[];
  178. /**
  179. * Array of metadata for a component's `@Event`s
  180. */
  181. events: JsonDocsEvent[];
  182. /**
  183. * Array of metadata for a component's `@Listen` handlers
  184. */
  185. listeners: JsonDocsListener[];
  186. /**
  187. * Array of metadata for a component's CSS styling information
  188. */
  189. styles: JsonDocsStyle[];
  190. /**
  191. * Array of component Slot information, generated from `@slot` tags
  192. */
  193. slots: JsonDocsSlot[];
  194. /**
  195. * Array of component Parts information, generate from `@part` tags
  196. */
  197. parts: JsonDocsPart[];
  198. /**
  199. * Array of metadata describing where the current component is used
  200. */
  201. dependents: string[];
  202. /**
  203. * Array of metadata listing the components which are used in current component
  204. */
  205. dependencies: string[];
  206. /**
  207. * Describes a tree of components coupling
  208. */
  209. dependencyGraph: JsonDocsDependencyGraph;
  210. /**
  211. * A deprecation reason/description found following a `@deprecated` tag
  212. */
  213. deprecation?: string;
  214. }
  215. export interface JsonDocsDependencyGraph {
  216. [tagName: string]: string[];
  217. }
  218. /**
  219. * A descriptor for a single JSDoc tag found in a block comment
  220. */
  221. export interface JsonDocsTag {
  222. /**
  223. * The tag name (immediately following the '@')
  224. */
  225. name: string;
  226. /**
  227. * The description that immediately follows the tag name
  228. */
  229. text?: string;
  230. }
  231. export interface JsonDocsValue {
  232. value?: string;
  233. type: string;
  234. }
  235. /**
  236. * A mapping of file names to their contents.
  237. *
  238. * This type is meant to be used when reading one or more usage markdown files associated with a component. For the
  239. * given directory structure:
  240. * ```
  241. * src/components/my-component
  242. * ├── my-component.tsx
  243. * └── usage
  244. * ├── bar.md
  245. * └── foo.md
  246. * ```
  247. * an instance of this type would include the name of the markdown file, mapped to its contents:
  248. * ```ts
  249. * {
  250. * 'bar': STRING_CONTENTS_OF_BAR.MD
  251. * 'foo': STRING_CONTENTS_OF_FOO.MD
  252. * }
  253. * ```
  254. */
  255. export interface JsonDocsUsage {
  256. [key: string]: string;
  257. }
  258. /**
  259. * An intermediate representation of a `@Prop` decorated member's JSDoc
  260. */
  261. export interface JsonDocsProp {
  262. /**
  263. * the name of the prop
  264. */
  265. name: string;
  266. complexType?: ComponentCompilerPropertyComplexType;
  267. /**
  268. * the type of the prop, in terms of the TypeScript type system (as opposed to JavaScript's or HTML's)
  269. */
  270. type: string;
  271. /**
  272. * `true` if the prop was configured as "mutable" where it was declared, `false` otherwise
  273. */
  274. mutable: boolean;
  275. /**
  276. * The name of the attribute that is exposed to configure a compiled web component
  277. */
  278. attr?: string;
  279. /**
  280. * `true` if the prop was configured to "reflect" back to HTML where it (the prop) was declared, `false` otherwise
  281. */
  282. reflectToAttr: boolean;
  283. /**
  284. * the JSDoc description text associated with the prop
  285. */
  286. docs: string;
  287. /**
  288. * JSDoc tags associated with the prop
  289. */
  290. docsTags: JsonDocsTag[];
  291. /**
  292. * The default value of the prop
  293. */
  294. default?: string;
  295. /**
  296. * Deprecation text associated with the prop. This is the text that immediately follows a `@deprecated` tag
  297. */
  298. deprecation?: string;
  299. values: JsonDocsValue[];
  300. /**
  301. * `true` if a component is declared with a '?', `false` otherwise
  302. *
  303. * @example
  304. * ```tsx
  305. * @Prop() componentProps?: any;
  306. * ```
  307. */
  308. optional: boolean;
  309. /**
  310. * `true` if a component is declared with a '!', `false` otherwise
  311. *
  312. * @example
  313. * ```tsx
  314. * @Prop() componentProps!: any;
  315. * ```
  316. */
  317. required: boolean;
  318. }
  319. export interface JsonDocsMethod {
  320. name: string;
  321. docs: string;
  322. docsTags: JsonDocsTag[];
  323. deprecation?: string;
  324. signature: string;
  325. returns: JsonDocsMethodReturn;
  326. parameters: JsonDocMethodParameter[];
  327. complexType: ComponentCompilerMethodComplexType;
  328. }
  329. export interface JsonDocsMethodReturn {
  330. type: string;
  331. docs: string;
  332. }
  333. export interface JsonDocMethodParameter {
  334. name: string;
  335. type: string;
  336. docs: string;
  337. }
  338. export interface JsonDocsEvent {
  339. event: string;
  340. bubbles: boolean;
  341. cancelable: boolean;
  342. composed: boolean;
  343. complexType: ComponentCompilerEventComplexType;
  344. docs: string;
  345. docsTags: JsonDocsTag[];
  346. deprecation?: string;
  347. detail: string;
  348. }
  349. /**
  350. * Type describing a CSS Style, as described by a JSDoc-style comment
  351. */
  352. export interface JsonDocsStyle {
  353. /**
  354. * The name of the style
  355. */
  356. name: string;
  357. /**
  358. * The type/description associated with the style
  359. */
  360. docs: string;
  361. /**
  362. * The annotation used in the JSDoc of the style (e.g. `@prop`)
  363. */
  364. annotation: string;
  365. /**
  366. * The mode associated with the style
  367. */
  368. mode: string | undefined;
  369. }
  370. export interface JsonDocsListener {
  371. event: string;
  372. target?: string;
  373. capture: boolean;
  374. passive: boolean;
  375. }
  376. /**
  377. * A descriptor for a slot
  378. *
  379. * Objects of this type are translated from the JSDoc tag, `@slot`
  380. */
  381. export interface JsonDocsSlot {
  382. /**
  383. * The name of the slot. Defaults to an empty string for an unnamed slot.
  384. */
  385. name: string;
  386. /**
  387. * A textual description of the slot.
  388. */
  389. docs: string;
  390. }
  391. /**
  392. * A descriptor of a CSS Shadow Part
  393. *
  394. * Objects of this type are translated from the JSDoc tag, `@part`, or the 'part'
  395. * attribute on a component in TSX
  396. */
  397. export interface JsonDocsPart {
  398. /**
  399. * The name of the Shadow part
  400. */
  401. name: string;
  402. /**
  403. * A textual description of the Shadow part.
  404. */
  405. docs: string;
  406. }
  407. /**
  408. * Represents a parsed block comment in a CSS, Sass, etc. file for a custom property.
  409. */
  410. export interface StyleDoc {
  411. /**
  412. * The name of the CSS property
  413. */
  414. name: string;
  415. /**
  416. * The user-defined description of the CSS property
  417. */
  418. docs: string;
  419. /**
  420. * The JSDoc-style annotation (e.g. `@prop`) that was used in the block comment to detect the comment.
  421. * Used to inform Stencil where the start of a new property's description starts (and where the previous description
  422. * ends).
  423. */
  424. annotation: "prop";
  425. /**
  426. * The Stencil style-mode that is associated with this property.
  427. */
  428. mode: string | undefined;
  429. }
  430. export {};
  431. declare const _default: JsonDocs;
  432. export default _default;