stencil-private.d.ts 71 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283
  1. import { result } from './utils';
  2. import type { InMemoryFileSystem } from '../compiler/sys/in-memory-fs';
  3. import type { CPSerializable } from './child_process';
  4. import type { BuildEvents, BuildLog, BuildResultsComponentGraph, CompilerBuildResults, CompilerFsStats, CompilerRequestResponse, CompilerSystem, Config, CopyResults, DevServerConfig, DevServerEditor, Diagnostic, Logger, LoggerLineUpdater, LoggerTimeSpan, OptimizeCssInput, OptimizeCssOutput, OutputTarget, OutputTargetWww, PageReloadStrategy, PrerenderConfig, StyleDoc, TaskCommand, ValidatedConfig } from './stencil-public-compiler';
  5. import type { JsonDocMethodParameter } from './stencil-public-docs';
  6. import type { ComponentInterface, ListenTargetOptions, VNode } from './stencil-public-runtime';
  7. export interface SourceMap {
  8. file: string;
  9. mappings: string;
  10. names: string[];
  11. sourceRoot?: string;
  12. sources: string[];
  13. sourcesContent?: string[];
  14. version: number;
  15. }
  16. export interface PrintLine {
  17. lineIndex: number;
  18. lineNumber: number;
  19. text: string;
  20. errorCharStart: number;
  21. errorLength?: number;
  22. }
  23. export interface AssetsMeta {
  24. absolutePath: string;
  25. cmpRelativePath: string;
  26. originalComponentPath: string;
  27. }
  28. export interface ParsedImport {
  29. importPath: string;
  30. basename: string;
  31. ext: string;
  32. data: ImportData;
  33. }
  34. export interface ImportData {
  35. tag?: string;
  36. encapsulation?: string;
  37. mode?: string;
  38. }
  39. export interface SerializeImportData extends ImportData {
  40. importeePath: string;
  41. importerPath?: string;
  42. }
  43. export interface BuildFeatures {
  44. style: boolean;
  45. mode: boolean;
  46. formAssociated: boolean;
  47. shadowDom: boolean;
  48. shadowDelegatesFocus: boolean;
  49. scoped: boolean;
  50. /**
  51. * Every component has a render function
  52. */
  53. allRenderFn: boolean;
  54. /**
  55. * At least one component has a render function
  56. */
  57. hasRenderFn: boolean;
  58. vdomRender: boolean;
  59. vdomAttribute: boolean;
  60. vdomClass: boolean;
  61. vdomFunctional: boolean;
  62. vdomKey: boolean;
  63. vdomListener: boolean;
  64. vdomPropOrAttr: boolean;
  65. vdomRef: boolean;
  66. vdomStyle: boolean;
  67. vdomText: boolean;
  68. vdomXlink: boolean;
  69. slotRelocation: boolean;
  70. slot: boolean;
  71. svg: boolean;
  72. element: boolean;
  73. event: boolean;
  74. hostListener: boolean;
  75. hostListenerTargetWindow: boolean;
  76. hostListenerTargetDocument: boolean;
  77. hostListenerTargetBody: boolean;
  78. /**
  79. * @deprecated Prevented from new apps, but left in for older collections
  80. */
  81. hostListenerTargetParent: boolean;
  82. hostListenerTarget: boolean;
  83. method: boolean;
  84. prop: boolean;
  85. propMutable: boolean;
  86. state: boolean;
  87. watchCallback: boolean;
  88. member: boolean;
  89. updatable: boolean;
  90. propBoolean: boolean;
  91. propNumber: boolean;
  92. propString: boolean;
  93. lifecycle: boolean;
  94. cmpDidLoad: boolean;
  95. cmpShouldUpdate: boolean;
  96. cmpWillLoad: boolean;
  97. cmpDidUpdate: boolean;
  98. cmpWillUpdate: boolean;
  99. cmpWillRender: boolean;
  100. cmpDidRender: boolean;
  101. cmpDidUnload: boolean;
  102. connectedCallback: boolean;
  103. disconnectedCallback: boolean;
  104. asyncLoading: boolean;
  105. observeAttribute: boolean;
  106. reflect: boolean;
  107. taskQueue: boolean;
  108. }
  109. export interface BuildConditionals extends Partial<BuildFeatures> {
  110. hotModuleReplacement?: boolean;
  111. isDebug?: boolean;
  112. isTesting?: boolean;
  113. isDev?: boolean;
  114. devTools?: boolean;
  115. invisiblePrehydration?: boolean;
  116. hydrateServerSide?: boolean;
  117. hydrateClientSide?: boolean;
  118. lifecycleDOMEvents?: boolean;
  119. cssAnnotations?: boolean;
  120. lazyLoad?: boolean;
  121. profile?: boolean;
  122. constructableCSS?: boolean;
  123. appendChildSlotFix?: boolean;
  124. slotChildNodesFix?: boolean;
  125. scopedSlotTextContentFix?: boolean;
  126. cloneNodeFix?: boolean;
  127. hydratedAttribute?: boolean;
  128. hydratedClass?: boolean;
  129. hydratedSelectorName?: string;
  130. initializeNextTick?: boolean;
  131. scriptDataOpts?: boolean;
  132. shadowDomShim?: boolean;
  133. asyncQueue?: boolean;
  134. transformTagName?: boolean;
  135. attachStyles?: boolean;
  136. experimentalSlotFixes?: boolean;
  137. experimentalScopedSlotChanges?: boolean;
  138. }
  139. export type ModuleFormat = 'amd' | 'cjs' | 'es' | 'iife' | 'system' | 'umd' | 'commonjs' | 'esm' | 'module' | 'systemjs';
  140. export interface RollupResultModule {
  141. id: string;
  142. }
  143. export interface RollupResults {
  144. modules: RollupResultModule[];
  145. }
  146. export interface UpdatedLazyBuildCtx {
  147. name: 'esm-browser' | 'esm' | 'cjs' | 'system';
  148. buildCtx: BuildCtx;
  149. }
  150. export interface BuildCtx {
  151. buildId: number;
  152. buildResults: CompilerBuildResults;
  153. buildStats?: result.Result<CompilerBuildStats, {
  154. diagnostics: Diagnostic[];
  155. }>;
  156. buildMessages: string[];
  157. bundleBuildCount: number;
  158. collections: CollectionCompilerMeta[];
  159. compilerCtx: CompilerCtx;
  160. esmBrowserComponentBundle: ReadonlyArray<BundleModule>;
  161. esmComponentBundle: ReadonlyArray<BundleModule>;
  162. es5ComponentBundle: ReadonlyArray<BundleModule>;
  163. systemComponentBundle: ReadonlyArray<BundleModule>;
  164. commonJsComponentBundle: ReadonlyArray<BundleModule>;
  165. components: ComponentCompilerMeta[];
  166. componentGraph: Map<string, string[]>;
  167. config: ValidatedConfig;
  168. createTimeSpan(msg: string, debug?: boolean): LoggerTimeSpan;
  169. data: any;
  170. debug: (msg: string) => void;
  171. diagnostics: Diagnostic[];
  172. dirsAdded: string[];
  173. dirsDeleted: string[];
  174. entryModules: EntryModule[];
  175. filesAdded: string[];
  176. filesChanged: string[];
  177. filesDeleted: string[];
  178. filesUpdated: string[];
  179. filesWritten: string[];
  180. globalStyle: string | undefined;
  181. hasConfigChanges: boolean;
  182. hasError: boolean;
  183. hasFinished: boolean;
  184. hasHtmlChanges: boolean;
  185. hasPrintedResults: boolean;
  186. hasServiceWorkerChanges: boolean;
  187. hasScriptChanges: boolean;
  188. hasStyleChanges: boolean;
  189. hasWarning: boolean;
  190. hydrateAppFilePath: string;
  191. indexBuildCount: number;
  192. indexDoc: Document;
  193. isRebuild: boolean;
  194. /**
  195. * A collection of Stencil's intermediate representation of components, tied to the current build
  196. */
  197. moduleFiles: Module[];
  198. packageJson: PackageJsonData;
  199. pendingCopyTasks: Promise<CopyResults>[];
  200. progress(task: BuildTask): void;
  201. requiresFullBuild: boolean;
  202. rollupResults?: RollupResults;
  203. scriptsAdded: string[];
  204. scriptsDeleted: string[];
  205. startTime: number;
  206. styleBuildCount: number;
  207. stylesPromise: Promise<void>;
  208. stylesUpdated: BuildStyleUpdate[];
  209. timeSpan: LoggerTimeSpan;
  210. timestamp: string;
  211. transpileBuildCount: number;
  212. validateTypesBuild?(): Promise<void>;
  213. validateTypesHandler?: (results: any) => Promise<void>;
  214. validateTypesPromise?: Promise<any>;
  215. }
  216. export interface BuildStyleUpdate {
  217. styleTag: string;
  218. styleText: string;
  219. styleMode: string;
  220. }
  221. export type BuildTask = any;
  222. export interface CompilerBuildStats {
  223. timestamp: string;
  224. compiler: {
  225. name: string;
  226. version: string;
  227. };
  228. app: {
  229. namespace: string;
  230. fsNamespace: string;
  231. components: number;
  232. entries: number;
  233. bundles: number;
  234. outputs: any;
  235. };
  236. options: {
  237. minifyJs: boolean;
  238. minifyCss: boolean;
  239. hashFileNames: boolean;
  240. hashedFileNameLength: number;
  241. buildEs5: boolean | 'prod';
  242. };
  243. formats: {
  244. esmBrowser: ReadonlyArray<CompilerBuildStatBundle>;
  245. esm: ReadonlyArray<CompilerBuildStatBundle>;
  246. es5: ReadonlyArray<CompilerBuildStatBundle>;
  247. system: ReadonlyArray<CompilerBuildStatBundle>;
  248. commonjs: ReadonlyArray<CompilerBuildStatBundle>;
  249. };
  250. components: BuildComponent[];
  251. entries: EntryModule[];
  252. rollupResults: RollupResults;
  253. sourceGraph?: BuildSourceGraph;
  254. componentGraph: BuildResultsComponentGraph;
  255. collections: CompilerBuildStatCollection[];
  256. }
  257. export interface CompilerBuildStatCollection {
  258. name: string;
  259. source: string;
  260. tags: string[][];
  261. }
  262. export interface CompilerBuildStatBundle {
  263. key: string;
  264. components: string[];
  265. bundleId: string;
  266. fileName: string;
  267. imports: string[];
  268. originalByteSize: number;
  269. }
  270. export interface BuildSourceGraph {
  271. [filePath: string]: string[];
  272. }
  273. export interface BuildComponent {
  274. tag: string;
  275. dependencyOf?: string[];
  276. dependencies?: string[];
  277. }
  278. export type SourceTarget = 'es5' | 'es2017' | 'latest';
  279. /**
  280. * A note regarding Rollup types:
  281. * As of this writing, there is no great way to import external types for packages that are directly embedded in the
  282. * Stencil source. As a result, some types are duplicated here for Rollup that will be used within the codebase.
  283. * Updates to rollup may require these typings to be updated.
  284. */
  285. export type RollupResult = RollupChunkResult | RollupAssetResult;
  286. export interface RollupAssetResult {
  287. type: 'asset';
  288. fileName: string;
  289. content: string;
  290. }
  291. export interface RollupChunkResult {
  292. type: 'chunk';
  293. entryKey: string;
  294. fileName: string;
  295. code: string;
  296. isEntry: boolean;
  297. isComponent: boolean;
  298. isCore: boolean;
  299. isIndex: boolean;
  300. isBrowserLoader: boolean;
  301. imports: string[];
  302. moduleFormat: ModuleFormat;
  303. map?: RollupSourceMap;
  304. }
  305. export interface RollupSourceMap {
  306. file: string;
  307. mappings: string;
  308. names: string[];
  309. sources: string[];
  310. sourcesContent: string[];
  311. version: number;
  312. toString(): string;
  313. toUrl(): string;
  314. }
  315. /**
  316. * Result of Stencil compressing, mangling, and otherwise 'minifying' JavaScript
  317. */
  318. export type OptimizeJsResult = {
  319. output: string;
  320. diagnostics: Diagnostic[];
  321. sourceMap?: SourceMap;
  322. };
  323. export interface BundleModule {
  324. entryKey: string;
  325. rollupResult: RollupChunkResult;
  326. cmps: ComponentCompilerMeta[];
  327. output: BundleModuleOutput;
  328. }
  329. export interface BundleModuleOutput {
  330. bundleId: string;
  331. fileName: string;
  332. code: string;
  333. }
  334. export interface Cache {
  335. get(key: string): Promise<string | null>;
  336. put(key: string, value: string): Promise<boolean>;
  337. has(key: string): Promise<boolean>;
  338. createKey(domain: string, ...args: any[]): Promise<string>;
  339. commit(): Promise<void>;
  340. clear(): void;
  341. clearDiskCache(): Promise<void>;
  342. getMemoryStats(): string;
  343. initCacheDir(): Promise<void>;
  344. }
  345. export interface CollectionCompilerMeta {
  346. collectionName: string;
  347. moduleId?: string;
  348. moduleDir: string;
  349. moduleFiles: Module[];
  350. global?: Module;
  351. compiler?: CollectionCompilerVersion;
  352. isInitialized?: boolean;
  353. hasExports?: boolean;
  354. dependencies?: string[];
  355. bundles?: {
  356. components: string[];
  357. }[];
  358. }
  359. export interface CollectionCompilerVersion {
  360. name: string;
  361. version: string;
  362. typescriptVersion?: string;
  363. }
  364. export interface CollectionManifest {
  365. entries?: CollectionComponentEntryPath[];
  366. collections?: CollectionDependencyManifest[];
  367. global?: string;
  368. compiler?: CollectionCompilerVersion;
  369. bundles?: CollectionBundleManifest[];
  370. }
  371. export type CollectionComponentEntryPath = string;
  372. export interface CollectionBundleManifest {
  373. components: string[];
  374. }
  375. export interface CollectionDependencyManifest {
  376. name: string;
  377. tags: string[];
  378. }
  379. export interface CollectionCompiler {
  380. name: string;
  381. version: string;
  382. typescriptVersion?: string;
  383. }
  384. export interface CollectionDependencyData {
  385. name: string;
  386. tags: string[];
  387. }
  388. export interface CompilerCtx {
  389. version: number;
  390. activeBuildId: number;
  391. activeDirsAdded: string[];
  392. activeDirsDeleted: string[];
  393. activeFilesAdded: string[];
  394. activeFilesDeleted: string[];
  395. activeFilesUpdated: string[];
  396. addWatchDir: (path: string, recursive: boolean) => void;
  397. addWatchFile: (path: string) => void;
  398. cache: Cache;
  399. cssModuleImports: Map<string, string[]>;
  400. cachedGlobalStyle: string;
  401. collections: CollectionCompilerMeta[];
  402. compilerOptions: any;
  403. events: BuildEvents;
  404. fs: InMemoryFileSystem;
  405. hasSuccessfulBuild: boolean;
  406. isActivelyBuilding: boolean;
  407. lastBuildResults: CompilerBuildResults;
  408. /**
  409. * A mapping of a file path to a Stencil {@link Module}
  410. */
  411. moduleMap: ModuleMap;
  412. nodeMap: NodeMap;
  413. resolvedCollections: Set<string>;
  414. rollupCacheHydrate: any;
  415. rollupCacheLazy: any;
  416. rollupCacheNative: any;
  417. styleModeNames: Set<string>;
  418. changedModules: Set<string>;
  419. changedFiles: Set<string>;
  420. worker?: CompilerWorkerContext;
  421. rollupCache: Map<string, any>;
  422. reset(): void;
  423. }
  424. export type NodeMap = WeakMap<any, ComponentCompilerMeta>;
  425. /**
  426. * Record, for a specific component, whether or not it has various features
  427. * which need to be handled correctly in the compilation pipeline.
  428. *
  429. * Note: this must be serializable to JSON.
  430. */
  431. export interface ComponentCompilerFeatures {
  432. hasAttribute: boolean;
  433. hasAttributeChangedCallbackFn: boolean;
  434. hasComponentWillLoadFn: boolean;
  435. hasComponentDidLoadFn: boolean;
  436. hasComponentShouldUpdateFn: boolean;
  437. hasComponentWillUpdateFn: boolean;
  438. hasComponentDidUpdateFn: boolean;
  439. hasComponentWillRenderFn: boolean;
  440. hasComponentDidRenderFn: boolean;
  441. hasComponentDidUnloadFn: boolean;
  442. hasConnectedCallbackFn: boolean;
  443. hasDisconnectedCallbackFn: boolean;
  444. hasElement: boolean;
  445. hasEvent: boolean;
  446. hasLifecycle: boolean;
  447. hasListener: boolean;
  448. hasListenerTarget: boolean;
  449. hasListenerTargetWindow: boolean;
  450. hasListenerTargetDocument: boolean;
  451. hasListenerTargetBody: boolean;
  452. /**
  453. * @deprecated Prevented from new apps, but left in for older collections
  454. */
  455. hasListenerTargetParent: boolean;
  456. hasMember: boolean;
  457. hasMethod: boolean;
  458. hasMode: boolean;
  459. hasProp: boolean;
  460. hasPropBoolean: boolean;
  461. hasPropNumber: boolean;
  462. hasPropString: boolean;
  463. hasPropMutable: boolean;
  464. hasReflect: boolean;
  465. hasRenderFn: boolean;
  466. hasState: boolean;
  467. hasStyle: boolean;
  468. hasVdomAttribute: boolean;
  469. hasVdomClass: boolean;
  470. hasVdomFunctional: boolean;
  471. hasVdomKey: boolean;
  472. hasVdomListener: boolean;
  473. hasVdomPropOrAttr: boolean;
  474. hasVdomRef: boolean;
  475. hasVdomRender: boolean;
  476. hasVdomStyle: boolean;
  477. hasVdomText: boolean;
  478. hasVdomXlink: boolean;
  479. hasWatchCallback: boolean;
  480. htmlAttrNames: string[];
  481. htmlTagNames: string[];
  482. htmlParts: string[];
  483. isUpdateable: boolean;
  484. /**
  485. * A plain component is one that doesn't have:
  486. * - any members decorated with `@Prop()`, `@State()`, `@Element()`, `@Method()`
  487. * - any methods decorated with `@Listen()`
  488. * - any styles
  489. * - any lifecycle methods, including `render()`
  490. */
  491. isPlain: boolean;
  492. /**
  493. * A collection of tag names of web components that a component references in its JSX/h() function
  494. */
  495. potentialCmpRefs: string[];
  496. }
  497. /**
  498. * Metadata about a given component
  499. *
  500. * Note: must be serializable to JSON!
  501. */
  502. export interface ComponentCompilerMeta extends ComponentCompilerFeatures {
  503. assetsDirs: CompilerAssetDir[];
  504. /**
  505. * The name to which an `ElementInternals` object (the return value of
  506. * `HTMLElement.attachInternals`) should be attached at runtime. If this is
  507. * `null` then `attachInternals` should not be called.
  508. */
  509. attachInternalsMemberName: string | null;
  510. componentClassName: string;
  511. /**
  512. * A list of web component tag names that are either:
  513. * - directly referenced in a Stencil component's JSX/h() function
  514. * - are referenced by a web component that is directly referenced in a Stencil component's JSX/h() function
  515. */
  516. dependencies: string[];
  517. /**
  518. * A list of web component tag names that either:
  519. * - directly reference the current component directly in their JSX/h() function
  520. * - indirectly/transitively reference the current component directly in their JSX/h() function
  521. */
  522. dependents: string[];
  523. /**
  524. * A list of web component tag names that are directly referenced in a Stencil component's JSX/h() function
  525. */
  526. directDependencies: string[];
  527. /**
  528. * A list of web component tag names that the current component directly in their JSX/h() function
  529. */
  530. directDependents: string[];
  531. docs: CompilerJsDoc;
  532. elementRef: string;
  533. encapsulation: Encapsulation;
  534. events: ComponentCompilerEvent[];
  535. excludeFromCollection: boolean;
  536. /**
  537. * Whether or not the component is form-associated
  538. */
  539. formAssociated: boolean;
  540. internal: boolean;
  541. isCollectionDependency: boolean;
  542. jsFilePath: string;
  543. listeners: ComponentCompilerListener[];
  544. methods: ComponentCompilerMethod[];
  545. properties: ComponentCompilerProperty[];
  546. shadowDelegatesFocus: boolean;
  547. sourceFilePath: string;
  548. sourceMapPath: string;
  549. states: ComponentCompilerState[];
  550. styleDocs: CompilerStyleDoc[];
  551. styles: StyleCompiler[];
  552. tagName: string;
  553. virtualProperties: ComponentCompilerVirtualProperty[];
  554. watchers: ComponentCompilerWatch[];
  555. }
  556. /**
  557. * The supported style encapsulation modes on a Stencil component:
  558. * 1. 'shadow' - native Shadow DOM
  559. * 2. 'scoped' - encapsulated styles and polyfilled slots
  560. * 3. 'none' - a basic HTML element
  561. */
  562. export type Encapsulation = 'shadow' | 'scoped' | 'none';
  563. /**
  564. * Intermediate Representation (IR) of a static property on a Stencil component
  565. */
  566. export interface ComponentCompilerStaticProperty {
  567. mutable: boolean;
  568. optional: boolean;
  569. required: boolean;
  570. type: ComponentCompilerPropertyType;
  571. complexType: ComponentCompilerPropertyComplexType;
  572. attribute?: string;
  573. reflect?: boolean;
  574. docs: CompilerJsDoc;
  575. defaultValue?: string;
  576. }
  577. /**
  578. * Intermediate Representation (IR) of a property on a Stencil component
  579. */
  580. export interface ComponentCompilerProperty extends ComponentCompilerStaticProperty {
  581. name: string;
  582. internal: boolean;
  583. }
  584. export interface ComponentCompilerVirtualProperty {
  585. name: string;
  586. type: string;
  587. docs: string;
  588. }
  589. export type ComponentCompilerPropertyType = 'any' | 'string' | 'boolean' | 'number' | 'unknown';
  590. /**
  591. * Information about a type used in a Stencil component or exported
  592. * from a Stencil project.
  593. */
  594. export interface ComponentCompilerPropertyComplexType {
  595. /**
  596. * The string of the original type annotation in the Stencil source code
  597. */
  598. original: string;
  599. /**
  600. * A 'resolved' type, where e.g. imported types have been resolved and inlined
  601. *
  602. * For instance, an annotation like `(foo: Foo) => string;` will be
  603. * converted to `(foo: { foo: string }) => string;`.
  604. */
  605. resolved: string;
  606. /**
  607. * A record of the types which were referenced in the assorted type
  608. * annotation in the original source file.
  609. */
  610. references: ComponentCompilerTypeReferences;
  611. }
  612. /**
  613. * A record of `ComponentCompilerTypeReference` entities.
  614. *
  615. * Each key in this record is intended to be the names of the types used by a component. However, this is not enforced
  616. * by the type system (I.E. any string can be used as a key).
  617. *
  618. * Note any key can be a user defined type or a TypeScript standard type.
  619. */
  620. export type ComponentCompilerTypeReferences = Record<string, ComponentCompilerTypeReference>;
  621. /**
  622. * Describes a reference to a type used by a component.
  623. */
  624. export interface ComponentCompilerTypeReference {
  625. /**
  626. * A type may be defined:
  627. * - locally (in the same file as the component that uses it)
  628. * - globally
  629. * - by importing it into a file (and is defined elsewhere)
  630. */
  631. location: 'local' | 'global' | 'import';
  632. /**
  633. * The path to the type reference, if applicable (global types should not need a path associated with them)
  634. */
  635. path?: string;
  636. /**
  637. * An ID for this type which is unique within a Stencil project.
  638. */
  639. id: string;
  640. }
  641. /**
  642. * Information about a type which is referenced by another type on a Stencil
  643. * component, for instance a {@link ComponentCompilerPropertyComplexType} or a
  644. * {@link ComponentCompilerEventComplexType}.
  645. */
  646. export interface ComponentCompilerReferencedType {
  647. /**
  648. * The path to the module where the type is declared.
  649. */
  650. path: string;
  651. /**
  652. * The string of the original type annotation in the Stencil source code
  653. */
  654. declaration: string;
  655. /**
  656. * An extracted docstring
  657. */
  658. docstring: string;
  659. }
  660. export interface ComponentCompilerStaticEvent {
  661. name: string;
  662. method: string;
  663. bubbles: boolean;
  664. cancelable: boolean;
  665. composed: boolean;
  666. docs: CompilerJsDoc;
  667. complexType: ComponentCompilerEventComplexType;
  668. }
  669. export interface ComponentCompilerEvent extends ComponentCompilerStaticEvent {
  670. internal: boolean;
  671. }
  672. export interface ComponentCompilerEventComplexType {
  673. original: string;
  674. resolved: string;
  675. references: ComponentCompilerTypeReferences;
  676. }
  677. export interface ComponentCompilerListener {
  678. name: string;
  679. method: string;
  680. capture: boolean;
  681. passive: boolean;
  682. target: ListenTargetOptions | undefined;
  683. }
  684. export interface ComponentCompilerStaticMethod {
  685. docs: CompilerJsDoc;
  686. complexType: ComponentCompilerMethodComplexType;
  687. }
  688. export interface ComponentCompilerMethodComplexType {
  689. signature: string;
  690. parameters: JsonDocMethodParameter[];
  691. references: ComponentCompilerTypeReferences;
  692. return: string;
  693. }
  694. export interface ComponentCompilerWatch {
  695. propName: string;
  696. methodName: string;
  697. }
  698. export interface ComponentCompilerMethod extends ComponentCompilerStaticMethod {
  699. name: string;
  700. internal: boolean;
  701. }
  702. export interface ComponentCompilerState {
  703. name: string;
  704. }
  705. /**
  706. * Representation of JSDoc that is pulled off a node in the AST
  707. */
  708. export interface CompilerJsDoc {
  709. /**
  710. * The text associated with the JSDoc
  711. */
  712. text: string;
  713. /**
  714. * Tags included in the JSDoc
  715. */
  716. tags: CompilerJsDocTagInfo[];
  717. }
  718. /**
  719. * Representation of a tag that exists in a JSDoc
  720. */
  721. export interface CompilerJsDocTagInfo {
  722. /**
  723. * The name of the tag - e.g. `@deprecated`
  724. */
  725. name: string;
  726. /**
  727. * Additional text that is associated with the tag - e.g. `@deprecated use v2 of this API`
  728. */
  729. text?: string;
  730. }
  731. /**
  732. * The (internal) representation of a CSS block comment in a CSS, Sass, etc. file. This data structure is used during
  733. * the initial compilation phases of Stencil, as a piece of {@link ComponentCompilerMeta}.
  734. */
  735. export interface CompilerStyleDoc {
  736. /**
  737. * The name of the CSS property
  738. */
  739. name: string;
  740. /**
  741. * The user-defined description of the CSS property
  742. */
  743. docs: string;
  744. /**
  745. * The JSDoc-style annotation (e.g. `@prop`) that was used in the block comment to detect the comment.
  746. * Used to inform Stencil where the start of a new property's description starts (and where the previous description
  747. * ends).
  748. */
  749. annotation: 'prop';
  750. /**
  751. * The Stencil style-mode that is associated with this property.
  752. */
  753. mode: string;
  754. }
  755. export interface CompilerAssetDir {
  756. absolutePath?: string;
  757. cmpRelativePath?: string;
  758. originalComponentPath?: string;
  759. }
  760. export interface ComponentCompilerData {
  761. exportLine: string;
  762. filePath: string;
  763. cmp: ComponentCompilerMeta;
  764. uniqueComponentClassName?: string;
  765. importLine?: string;
  766. }
  767. export interface ComponentConstructor {
  768. is?: string;
  769. properties?: ComponentConstructorProperties;
  770. watchers?: ComponentConstructorWatchers;
  771. events?: ComponentConstructorEvent[];
  772. listeners?: ComponentConstructorListener[];
  773. style?: string;
  774. styleId?: string;
  775. encapsulation?: ComponentConstructorEncapsulation;
  776. observedAttributes?: string[];
  777. cmpMeta?: ComponentRuntimeMeta;
  778. isProxied?: boolean;
  779. isStyleRegistered?: boolean;
  780. }
  781. /**
  782. * A mapping from class member names to a list of methods which are watching
  783. * them.
  784. */
  785. export interface ComponentConstructorWatchers {
  786. [propName: string]: string[];
  787. }
  788. export interface ComponentTestingConstructor extends ComponentConstructor {
  789. COMPILER_META: ComponentCompilerMeta;
  790. prototype?: {
  791. componentWillLoad?: Function;
  792. componentWillUpdate?: Function;
  793. componentWillRender?: Function;
  794. __componentWillLoad?: Function | null;
  795. __componentWillUpdate?: Function | null;
  796. __componentWillRender?: Function | null;
  797. };
  798. }
  799. export interface ComponentNativeConstructor extends ComponentConstructor {
  800. cmpMeta: ComponentRuntimeMeta;
  801. }
  802. export type ComponentConstructorEncapsulation = 'shadow' | 'scoped' | 'none';
  803. export interface ComponentConstructorProperties {
  804. [propName: string]: ComponentConstructorProperty;
  805. }
  806. export interface ComponentConstructorProperty {
  807. attribute?: string;
  808. elementRef?: boolean;
  809. method?: boolean;
  810. mutable?: boolean;
  811. reflect?: boolean;
  812. state?: boolean;
  813. type?: ComponentConstructorPropertyType;
  814. watchCallbacks?: string[];
  815. }
  816. export type ComponentConstructorPropertyType = StringConstructor | BooleanConstructor | NumberConstructor | 'string' | 'boolean' | 'number';
  817. export interface ComponentConstructorEvent {
  818. name: string;
  819. method: string;
  820. bubbles: boolean;
  821. cancelable: boolean;
  822. composed: boolean;
  823. }
  824. export interface ComponentConstructorListener {
  825. name: string;
  826. method: string;
  827. capture?: boolean;
  828. passive?: boolean;
  829. }
  830. export interface DevClientWindow extends Window {
  831. ['s-dev-server']: boolean;
  832. ['s-initial-load']: boolean;
  833. ['s-build-id']: number;
  834. WebSocket: new (socketUrl: string, protos: string[]) => WebSocket;
  835. devServerConfig?: DevClientConfig;
  836. }
  837. export interface DevClientConfig {
  838. basePath: string;
  839. editors: DevServerEditor[];
  840. reloadStrategy: PageReloadStrategy;
  841. socketUrl?: string;
  842. }
  843. export interface HttpRequest {
  844. method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS';
  845. acceptHeader: string;
  846. url: URL;
  847. searchParams: URLSearchParams;
  848. pathname?: string;
  849. filePath?: string;
  850. stats?: CompilerFsStats;
  851. headers?: {
  852. [name: string]: string;
  853. };
  854. host?: string;
  855. }
  856. export interface DevServerMessage {
  857. startServer?: DevServerConfig;
  858. closeServer?: boolean;
  859. serverStarted?: DevServerConfig;
  860. serverClosed?: boolean;
  861. buildStart?: boolean;
  862. buildLog?: BuildLog;
  863. buildResults?: CompilerBuildResults;
  864. requestBuildResults?: boolean;
  865. error?: {
  866. message?: string;
  867. type?: string;
  868. stack?: any;
  869. };
  870. isActivelyBuilding?: boolean;
  871. compilerRequestPath?: string;
  872. compilerRequestResults?: CompilerRequestResponse;
  873. requestLog?: {
  874. method: string;
  875. url: string;
  876. status: number;
  877. };
  878. }
  879. export type DevServerSendMessage = (msg: DevServerMessage) => void;
  880. export interface DevServerContext {
  881. connectorHtml: string;
  882. dirTemplate: string;
  883. getBuildResults: () => Promise<CompilerBuildResults>;
  884. getCompilerRequest: (path: string) => Promise<CompilerRequestResponse>;
  885. isServerListening: boolean;
  886. logRequest: (req: HttpRequest, status: number) => void;
  887. prerenderConfig: PrerenderConfig;
  888. serve302: (req: any, res: any, pathname?: string) => void;
  889. serve404: (req: any, res: any, xSource: string, content?: string) => void;
  890. serve500: (req: any, res: any, error: any, xSource: string) => void;
  891. sys: CompilerSystem;
  892. }
  893. export type InitServerProcess = (sendMsg: (msg: DevServerMessage) => void) => (msg: DevServerMessage) => void;
  894. export interface DevResponseHeaders {
  895. 'cache-control'?: string;
  896. expires?: string;
  897. 'content-type'?: string;
  898. 'content-length'?: number;
  899. date?: string;
  900. 'access-control-allow-origin'?: string;
  901. 'access-control-expose-headers'?: string;
  902. 'content-encoding'?: 'gzip';
  903. vary?: 'Accept-Encoding';
  904. server?: string;
  905. 'x-directory-index'?: string;
  906. 'x-source'?: string;
  907. }
  908. export interface OpenInEditorData {
  909. file?: string;
  910. line?: number;
  911. column?: number;
  912. open?: string;
  913. editor?: string;
  914. exists?: boolean;
  915. error?: string;
  916. }
  917. export interface EntryModule {
  918. entryKey: string;
  919. cmps: ComponentCompilerMeta[];
  920. }
  921. /**
  922. * An interface extending `HTMLElement` which describes the fields added onto
  923. * host HTML elements by the Stencil runtime.
  924. */
  925. export interface HostElement extends HTMLElement {
  926. connectedCallback?: () => void;
  927. attributeChangedCallback?: (attribName: string, oldVal: string, newVal: string, namespace: string) => void;
  928. disconnectedCallback?: () => void;
  929. host?: Element;
  930. forceUpdate?: () => void;
  931. /**
  932. * Unique stencil id for this element
  933. */
  934. ['s-id']?: string;
  935. /**
  936. * Content Reference:
  937. * Reference to the HTML Comment that's placed inside of the
  938. * host element's original content. This comment is used to
  939. * always represent where host element's light dom is.
  940. */
  941. ['s-cr']?: RenderNode;
  942. /**
  943. * Lifecycle ready
  944. */
  945. ['s-lr']?: boolean;
  946. /**
  947. * A reference to the `ElementInternals` object for the current host
  948. *
  949. * This is used for maintaining a reference to the object between HMR
  950. * refreshes in the lazy build.
  951. *
  952. * "stencil-element-internals"
  953. */
  954. ['s-ei']?: ElementInternals;
  955. /**
  956. * On Render Callbacks:
  957. * Array of callbacks to fire off after it has rendered.
  958. */
  959. ['s-rc']?: (() => void)[];
  960. /**
  961. * Scope Id
  962. * The scope id of this component when using scoped css encapsulation
  963. * or using shadow dom but the browser doesn't support it
  964. */
  965. ['s-sc']?: string;
  966. /**
  967. * Scope Ids
  968. * All the possible scope ids of this component when using scoped css encapsulation
  969. * or using shadow dom but the browser doesn't support it
  970. */
  971. ['s-scs']?: string[];
  972. /**
  973. * Hot Module Replacement, dev mode only
  974. *
  975. * This function should be defined by the HMR-supporting runtime and should
  976. * do the work of actually updating the component in-place.
  977. */
  978. ['s-hmr']?: (versionId: string) => void;
  979. ['s-p']?: Promise<void>[];
  980. componentOnReady?: () => Promise<this>;
  981. }
  982. export interface HydrateResults {
  983. buildId: string;
  984. diagnostics: Diagnostic[];
  985. url: string;
  986. host: string | null;
  987. hostname: string | null;
  988. href: string | null;
  989. port: string | null;
  990. pathname: string | null;
  991. search: string | null;
  992. hash: string | null;
  993. html: string | null;
  994. components: HydrateComponent[];
  995. anchors: HydrateAnchorElement[];
  996. imgs: HydrateImgElement[];
  997. scripts: HydrateScriptElement[];
  998. styles: HydrateStyleElement[];
  999. staticData: HydrateStaticData[];
  1000. title: string | null;
  1001. hydratedCount: number;
  1002. httpStatus: number | null;
  1003. }
  1004. export interface HydrateComponent {
  1005. tag: string;
  1006. mode: string;
  1007. count: number;
  1008. depth: number;
  1009. }
  1010. export interface HydrateElement {
  1011. [attrName: string]: string | undefined;
  1012. }
  1013. export interface HydrateAnchorElement extends HydrateElement {
  1014. href?: string;
  1015. target?: string;
  1016. }
  1017. export interface HydrateImgElement extends HydrateElement {
  1018. src?: string;
  1019. }
  1020. export interface HydrateScriptElement extends HydrateElement {
  1021. src?: string;
  1022. type?: string;
  1023. }
  1024. export interface HydrateStyleElement extends HydrateElement {
  1025. href?: string;
  1026. }
  1027. export interface HydrateStaticData {
  1028. id: string;
  1029. type: string;
  1030. content: string;
  1031. }
  1032. export interface JsDoc {
  1033. name: string;
  1034. documentation: string;
  1035. type: string;
  1036. tags: JSDocTagInfo[];
  1037. default?: string;
  1038. parameters?: JsDoc[];
  1039. returns?: {
  1040. type: string;
  1041. documentation: string;
  1042. };
  1043. }
  1044. export interface JSDocTagInfo {
  1045. name: string;
  1046. text?: string;
  1047. }
  1048. /**
  1049. * A mapping from a TypeScript or JavaScript source file path on disk, to a Stencil {@link Module}.
  1050. *
  1051. * It is advised that the key (path) be normalized before storing/retrieving the `Module` to avoid unnecessary lookup
  1052. * failures.
  1053. */
  1054. export type ModuleMap = Map<string, Module>;
  1055. /**
  1056. * Stencil's Intermediate Representation (IR) of a module, bundling together
  1057. * various pieces of information like the classes declared within it, the path
  1058. * to the original source file, HTML tag names defined in the file, and so on.
  1059. *
  1060. * Note that this gets serialized/parsed as JSON and therefore cannot contain a
  1061. * `Map` or a `Set`.
  1062. */
  1063. export interface Module {
  1064. cmps: ComponentCompilerMeta[];
  1065. /**
  1066. * A collection of modules that a component will need. The modules in this list must have import statements generated
  1067. * in order for the component to function.
  1068. */
  1069. coreRuntimeApis: string[];
  1070. /**
  1071. * A collection of modules that a component will need for a specific output target. The modules in this list must
  1072. * have import statements generated in order for the component to function, but only for a specific output target.
  1073. */
  1074. outputTargetCoreRuntimeApis: Partial<Record<OutputTarget['type'], string[]>>;
  1075. collectionName: string;
  1076. dtsFilePath: string;
  1077. excludeFromCollection: boolean;
  1078. externalImports: string[];
  1079. htmlAttrNames: string[];
  1080. htmlTagNames: string[];
  1081. htmlParts: string[];
  1082. isCollectionDependency: boolean;
  1083. isLegacy: boolean;
  1084. jsFilePath: string;
  1085. localImports: string[];
  1086. originalImports: string[];
  1087. originalCollectionComponentPath: string;
  1088. potentialCmpRefs: string[];
  1089. sourceFilePath: string;
  1090. staticSourceFile: any;
  1091. staticSourceFileText: string;
  1092. sourceMapPath: string;
  1093. sourceMapFileText: string;
  1094. hasVdomAttribute: boolean;
  1095. hasVdomClass: boolean;
  1096. hasVdomFunctional: boolean;
  1097. hasVdomKey: boolean;
  1098. hasVdomListener: boolean;
  1099. hasVdomPropOrAttr: boolean;
  1100. hasVdomRef: boolean;
  1101. hasVdomRender: boolean;
  1102. hasVdomStyle: boolean;
  1103. hasVdomText: boolean;
  1104. hasVdomXlink: boolean;
  1105. }
  1106. export interface Plugin {
  1107. name?: string;
  1108. pluginType?: string;
  1109. load?: (id: string, context: PluginCtx) => Promise<string> | string;
  1110. resolveId?: (importee: string, importer: string, context: PluginCtx) => Promise<string> | string;
  1111. transform?: (sourceText: string, id: string, context: PluginCtx) => Promise<PluginTransformResults> | PluginTransformResults | string;
  1112. }
  1113. export interface PluginTransformResults {
  1114. code?: string;
  1115. map?: string;
  1116. id?: string;
  1117. diagnostics?: Diagnostic[];
  1118. dependencies?: string[];
  1119. }
  1120. export interface PluginCtx {
  1121. config: Config;
  1122. sys: CompilerSystem;
  1123. fs: InMemoryFileSystem;
  1124. cache: Cache;
  1125. diagnostics: Diagnostic[];
  1126. }
  1127. export interface PrerenderUrlResults {
  1128. anchorUrls: string[];
  1129. diagnostics: Diagnostic[];
  1130. filePath: string;
  1131. }
  1132. export interface PrerenderUrlRequest {
  1133. appDir: string;
  1134. buildId: string;
  1135. baseUrl: string;
  1136. componentGraphPath: string;
  1137. devServerHostUrl: string;
  1138. hydrateAppFilePath: string;
  1139. isDebug: boolean;
  1140. prerenderConfigPath: string;
  1141. staticSite: boolean;
  1142. templateId: string;
  1143. url: string;
  1144. writeToFilePath: string;
  1145. }
  1146. export interface PrerenderManager {
  1147. config: Config;
  1148. prerenderUrlWorker: (prerenderRequest: PrerenderUrlRequest) => Promise<PrerenderUrlResults>;
  1149. devServerHostUrl: string;
  1150. diagnostics: Diagnostic[];
  1151. hydrateAppFilePath: string;
  1152. isDebug: boolean;
  1153. logCount: number;
  1154. outputTarget: OutputTargetWww;
  1155. prerenderConfig: PrerenderConfig;
  1156. prerenderConfigPath: string;
  1157. progressLogger?: LoggerLineUpdater;
  1158. resolve: Function;
  1159. staticSite: boolean;
  1160. templateId: string;
  1161. componentGraphPath: string;
  1162. urlsProcessing: Set<string>;
  1163. urlsPending: Set<string>;
  1164. urlsCompleted: Set<string>;
  1165. maxConcurrency: number;
  1166. }
  1167. /**
  1168. * Generic node that represents all of the
  1169. * different types of nodes we'd see when rendering
  1170. */
  1171. export interface RenderNode extends HostElement {
  1172. /**
  1173. * Shadow root's host
  1174. */
  1175. host?: Element;
  1176. /**
  1177. * On Ref Function:
  1178. * Callback function to be called when the slotted node ref is ready.
  1179. */
  1180. ['s-rf']?: (elm: Element) => unknown;
  1181. /**
  1182. * Is initially hidden
  1183. * Whether this node was originally rendered with the `hidden` attribute.
  1184. *
  1185. * Used to reset the `hidden` state of a node during slot relocation.
  1186. */
  1187. ['s-ih']?: boolean;
  1188. /**
  1189. * Is Content Reference Node:
  1190. * This node is a content reference node.
  1191. */
  1192. ['s-cn']?: boolean;
  1193. /**
  1194. * Is a slot reference node:
  1195. * This is a node that represents where a slot
  1196. * was originally located.
  1197. */
  1198. ['s-sr']?: boolean;
  1199. /**
  1200. * Slot name
  1201. */
  1202. ['s-sn']?: string;
  1203. /**
  1204. * Host element tag name:
  1205. * The tag name of the host element that this
  1206. * node was created in.
  1207. */
  1208. ['s-hn']?: string;
  1209. /**
  1210. * Slot host tag name:
  1211. * This is the tag name of the element where this node
  1212. * has been moved to during slot relocation.
  1213. *
  1214. * This allows us to check if the node has been moved and prevent
  1215. * us from thinking a node _should_ be moved when it may already be in
  1216. * its final destination.
  1217. *
  1218. * This value is set to `undefined` whenever the node is put back into its original location.
  1219. */
  1220. ['s-sh']?: string;
  1221. /**
  1222. * Original Location Reference:
  1223. * A reference pointing to the comment
  1224. * which represents the original location
  1225. * before it was moved to its slot.
  1226. */
  1227. ['s-ol']?: RenderNode;
  1228. /**
  1229. * Node reference:
  1230. * This is a reference for a original location node
  1231. * back to the node that's been moved around.
  1232. */
  1233. ['s-nr']?: RenderNode;
  1234. /**
  1235. * Scope Id
  1236. */
  1237. ['s-si']?: string;
  1238. /**
  1239. * Host Id (hydrate only)
  1240. */
  1241. ['s-host-id']?: number;
  1242. /**
  1243. * Node Id (hydrate only)
  1244. */
  1245. ['s-node-id']?: number;
  1246. /**
  1247. * Used to know the components encapsulation.
  1248. * empty "" for shadow, "c" from scoped
  1249. */
  1250. ['s-en']?: '' | /*shadow*/ 'c';
  1251. }
  1252. export type LazyBundlesRuntimeData = LazyBundleRuntimeData[];
  1253. export type LazyBundleRuntimeData = [
  1254. /** bundleIds */
  1255. string,
  1256. ComponentRuntimeMetaCompact[]
  1257. ];
  1258. export type ComponentRuntimeMetaCompact = [
  1259. /** flags */
  1260. number,
  1261. /** tagname */
  1262. string,
  1263. /** members */
  1264. {
  1265. [memberName: string]: ComponentRuntimeMember;
  1266. }?,
  1267. /** listeners */
  1268. ComponentRuntimeHostListener[]?,
  1269. /** watchers */
  1270. ComponentConstructorWatchers?
  1271. ];
  1272. /**
  1273. * Runtime metadata for a Stencil component
  1274. */
  1275. export interface ComponentRuntimeMeta {
  1276. /**
  1277. * This number is used to hold a series of bitflags for various features we
  1278. * support on components. The flags which this value is intended to store are
  1279. * documented in the `CMP_FLAGS` enum.
  1280. */
  1281. $flags$: number;
  1282. /**
  1283. * Just what it says on the tin - the tag name for the component, as set in
  1284. * the `@Component` decorator.
  1285. */
  1286. $tagName$: string;
  1287. /**
  1288. * A map of the component's members, which could include fields decorated
  1289. * with `@Prop`, `@State`, etc as well as methods.
  1290. */
  1291. $members$?: ComponentRuntimeMembers;
  1292. /**
  1293. * Information about listeners on the component.
  1294. */
  1295. $listeners$?: ComponentRuntimeHostListener[];
  1296. /**
  1297. * Tuples containing information about `@Prop` fields on the component which
  1298. * are set to be reflected (i.e. kept in sync) as HTML attributes when
  1299. * updated.
  1300. */
  1301. $attrsToReflect$?: ComponentRuntimeReflectingAttr[];
  1302. /**
  1303. * Information about which class members have watchers attached on the component.
  1304. */
  1305. $watchers$?: ComponentConstructorWatchers;
  1306. /**
  1307. * A bundle ID used for lazy loading.
  1308. */
  1309. $lazyBundleId$?: string;
  1310. }
  1311. /**
  1312. * A mapping of the names of members on the component to some runtime-specific
  1313. * information about them.
  1314. */
  1315. export interface ComponentRuntimeMembers {
  1316. [memberName: string]: ComponentRuntimeMember;
  1317. }
  1318. /**
  1319. * A tuple with information about a class member that's relevant at runtime.
  1320. * The fields are:
  1321. *
  1322. * 1. A number used to hold bitflags for component members. The bit flags which
  1323. * this is intended to store are documented in the `MEMBER_FLAGS` enum.
  1324. * 2. The attribute name to observe.
  1325. */
  1326. export type ComponentRuntimeMember = [number, string?];
  1327. /**
  1328. * A tuple holding information about a host listener which is relevant at
  1329. * runtime. The field are:
  1330. *
  1331. * 1. A number used to hold bitflags for listeners. The bit flags which this is
  1332. * intended to store are documented in the `LISTENER_FLAGS` enum.
  1333. * 2. The event name.
  1334. * 3. The method name.
  1335. */
  1336. export type ComponentRuntimeHostListener = [number, string, string];
  1337. /**
  1338. * A tuple containing information about props which are "reflected" at runtime,
  1339. * meaning that HTML attributes on the component instance are kept in sync with
  1340. * the prop value.
  1341. *
  1342. * The fields are:
  1343. *
  1344. * 1. the prop name
  1345. * 2. the prop attribute.
  1346. */
  1347. export type ComponentRuntimeReflectingAttr = [string, string | undefined];
  1348. /**
  1349. * A runtime component reference, consistent of either a host element _or_ an
  1350. * empty object. This is used in particular in a few different places as the
  1351. * keys in a `WeakMap` which maps {@link HostElement} instances to their
  1352. * associated {@link HostRef} instance.
  1353. */
  1354. export type RuntimeRef = HostElement | {};
  1355. /**
  1356. * Interface used to track an Element, it's virtual Node (`VNode`), and other data
  1357. */
  1358. export interface HostRef {
  1359. $ancestorComponent$?: HostElement;
  1360. $flags$: number;
  1361. $cmpMeta$: ComponentRuntimeMeta;
  1362. $hostElement$: HostElement;
  1363. $instanceValues$?: Map<string, any>;
  1364. $lazyInstance$?: ComponentInterface;
  1365. /**
  1366. * A promise that gets resolved if `BUILD.asyncLoading` is enabled and after the `componentDidLoad`
  1367. * and before the `componentDidUpdate` lifecycle events are triggered.
  1368. */
  1369. $onReadyPromise$?: Promise<HostElement>;
  1370. /**
  1371. * A callback which resolves {@link HostRef.$onReadyPromise$}
  1372. * @param elm host element
  1373. */
  1374. $onReadyResolve$?: (elm: HostElement) => void;
  1375. /**
  1376. * A promise which resolves with the host component once it has finished rendering
  1377. * for the first time. This is primarily used to wait for the first `update` to be
  1378. * called on a component.
  1379. */
  1380. $onInstancePromise$?: Promise<HostElement>;
  1381. /**
  1382. * A callback which resolves {@link HostRef.$onInstancePromise$}
  1383. * @param elm host element
  1384. */
  1385. $onInstanceResolve$?: (elm: HostElement) => void;
  1386. /**
  1387. * A promise which resolves when the component has finished rendering for the first time.
  1388. * It is called after {@link HostRef.$onInstancePromise$} resolves.
  1389. */
  1390. $onRenderResolve$?: () => void;
  1391. $vnode$?: VNode;
  1392. $queuedListeners$?: [string, any][];
  1393. $rmListeners$?: (() => void)[];
  1394. $modeName$?: string;
  1395. $renderCount$?: number;
  1396. }
  1397. export interface PlatformRuntime {
  1398. /**
  1399. * This number is used to hold a series of bitflags for various features we
  1400. * support within the runtime. The flags which this value is intended to store are
  1401. * documented in the {@link PLATFORM_FLAGS} enum.
  1402. */
  1403. $flags$: number;
  1404. /**
  1405. * Holds a map of nodes to be hydrated.
  1406. */
  1407. $orgLocNodes$?: Map<string, RenderNode>;
  1408. /**
  1409. * Holds the resource url for given platform environment.
  1410. */
  1411. $resourcesUrl$: string;
  1412. /**
  1413. * The nonce value to be applied to all script/style tags at runtime.
  1414. * If `null`, the nonce attribute will not be applied.
  1415. */
  1416. $nonce$?: string | null;
  1417. /**
  1418. * A utility function that executes a given function and returns the result.
  1419. * @param c The callback function to execute
  1420. */
  1421. jmp: (c: Function) => any;
  1422. /**
  1423. * A wrapper for {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame `requestAnimationFrame`}
  1424. */
  1425. raf: (c: FrameRequestCallback) => number;
  1426. /**
  1427. * A wrapper for {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener `addEventListener`}
  1428. */
  1429. ael: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;
  1430. /**
  1431. * A wrapper for {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener `removeEventListener`}
  1432. */
  1433. rel: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;
  1434. /**
  1435. * A wrapper for creating a {@link https://developer.mozilla.org/docs/Web/API/CustomEvent `CustomEvent`}
  1436. */
  1437. ce: (eventName: string, opts?: any) => CustomEvent;
  1438. }
  1439. export type StyleMap = Map<string, CSSStyleSheet | string>;
  1440. export type RootAppliedStyleMap = WeakMap<Element, Set<string>>;
  1441. export interface ScreenshotConnector {
  1442. initBuild(opts: ScreenshotConnectorOptions): Promise<void>;
  1443. completeBuild(masterBuild: ScreenshotBuild): Promise<ScreenshotBuildResults>;
  1444. getMasterBuild(): Promise<ScreenshotBuild>;
  1445. pullMasterBuild(): Promise<void>;
  1446. publishBuild(buildResults: ScreenshotBuildResults): Promise<ScreenshotBuildResults>;
  1447. getScreenshotCache(): Promise<ScreenshotCache>;
  1448. updateScreenshotCache(screenshotCache: ScreenshotCache, buildResults: ScreenshotBuildResults): Promise<ScreenshotCache>;
  1449. generateJsonpDataUris(build: ScreenshotBuild): Promise<void>;
  1450. sortScreenshots(screenshots: Screenshot[]): Screenshot[];
  1451. toJson(masterBuild: ScreenshotBuild, screenshotCache: ScreenshotCache): string;
  1452. }
  1453. export interface ScreenshotBuildResults {
  1454. appNamespace: string;
  1455. masterBuild: ScreenshotBuild;
  1456. currentBuild: ScreenshotBuild;
  1457. compare: ScreenshotCompareResults;
  1458. }
  1459. export interface ScreenshotCompareResults {
  1460. id: string;
  1461. a: {
  1462. id: string;
  1463. message: string;
  1464. author: string;
  1465. url: string;
  1466. previewUrl: string;
  1467. };
  1468. b: {
  1469. id: string;
  1470. message: string;
  1471. author: string;
  1472. url: string;
  1473. previewUrl: string;
  1474. };
  1475. timestamp: number;
  1476. url: string;
  1477. appNamespace: string;
  1478. diffs: ScreenshotDiff[];
  1479. }
  1480. export interface ScreenshotConnectorOptions {
  1481. buildId: string;
  1482. buildMessage: string;
  1483. buildAuthor?: string;
  1484. buildUrl?: string;
  1485. previewUrl?: string;
  1486. appNamespace: string;
  1487. buildTimestamp: number;
  1488. logger: Logger;
  1489. rootDir: string;
  1490. cacheDir: string;
  1491. packageDir: string;
  1492. screenshotDirName?: string;
  1493. imagesDirName?: string;
  1494. buildsDirName?: string;
  1495. currentBuildDir?: string;
  1496. updateMaster?: boolean;
  1497. allowableMismatchedPixels?: number;
  1498. allowableMismatchedRatio?: number;
  1499. pixelmatchThreshold?: number;
  1500. waitBeforeScreenshot?: number;
  1501. pixelmatchModulePath?: string;
  1502. }
  1503. export interface ScreenshotBuildData {
  1504. buildId: string;
  1505. rootDir: string;
  1506. screenshotDir: string;
  1507. imagesDir: string;
  1508. buildsDir: string;
  1509. currentBuildDir: string;
  1510. updateMaster: boolean;
  1511. allowableMismatchedPixels: number;
  1512. allowableMismatchedRatio: number;
  1513. pixelmatchThreshold: number;
  1514. masterScreenshots: {
  1515. [screenshotId: string]: string;
  1516. };
  1517. cache: {
  1518. [cacheKey: string]: number;
  1519. };
  1520. timeoutBeforeScreenshot: number;
  1521. pixelmatchModulePath: string;
  1522. }
  1523. export interface PixelMatchInput {
  1524. imageAPath: string;
  1525. imageBPath: string;
  1526. width: number;
  1527. height: number;
  1528. pixelmatchThreshold: number;
  1529. }
  1530. export interface ScreenshotBuild {
  1531. id: string;
  1532. message: string;
  1533. author?: string;
  1534. url?: string;
  1535. previewUrl?: string;
  1536. appNamespace: string;
  1537. timestamp: number;
  1538. screenshots: Screenshot[];
  1539. }
  1540. export interface ScreenshotCache {
  1541. timestamp?: number;
  1542. lastBuildId?: string;
  1543. size?: number;
  1544. items?: {
  1545. /**
  1546. * Cache key
  1547. */
  1548. key: string;
  1549. /**
  1550. * Timestamp used to remove the oldest data
  1551. */
  1552. ts: number;
  1553. /**
  1554. * Mismatched pixels
  1555. */
  1556. mp: number;
  1557. }[];
  1558. }
  1559. export interface Screenshot {
  1560. id: string;
  1561. desc?: string;
  1562. image: string;
  1563. device?: string;
  1564. userAgent?: string;
  1565. width: number;
  1566. height: number;
  1567. deviceScaleFactor?: number;
  1568. hasTouch?: boolean;
  1569. isLandscape?: boolean;
  1570. isMobile?: boolean;
  1571. testPath?: string;
  1572. diff?: ScreenshotDiff;
  1573. }
  1574. export interface ScreenshotDiff {
  1575. mismatchedPixels: number;
  1576. id: string;
  1577. desc?: string;
  1578. imageA?: string;
  1579. imageB?: string;
  1580. device?: string;
  1581. userAgent?: string;
  1582. width: number;
  1583. height: number;
  1584. deviceScaleFactor?: number;
  1585. hasTouch?: boolean;
  1586. isLandscape?: boolean;
  1587. isMobile?: boolean;
  1588. allowableMismatchedPixels: number;
  1589. allowableMismatchedRatio: number;
  1590. testPath?: string;
  1591. cacheKey?: string;
  1592. }
  1593. export interface ScreenshotOptions {
  1594. /**
  1595. * When true, takes a screenshot of the full scrollable page.
  1596. * Default: `false`
  1597. */
  1598. fullPage?: boolean;
  1599. /**
  1600. * An object which specifies clipping region of the page.
  1601. */
  1602. clip?: ScreenshotBoundingBox;
  1603. /**
  1604. * Hides default white background and allows capturing screenshots with transparency.
  1605. * Default: `false`
  1606. */
  1607. omitBackground?: boolean;
  1608. /**
  1609. * Matching threshold, ranges from `0` to 1. Smaller values make the comparison
  1610. * more sensitive. Defaults to the testing config `pixelmatchThreshold` value;
  1611. */
  1612. pixelmatchThreshold?: number;
  1613. /**
  1614. * Capture the screenshot beyond the viewport.
  1615. *
  1616. * @defaultValue `false` if there is no `clip`. `true` otherwise.
  1617. */
  1618. captureBeyondViewport?: boolean;
  1619. }
  1620. export interface ScreenshotBoundingBox {
  1621. /**
  1622. * The x-coordinate of top-left corner.
  1623. */
  1624. x: number;
  1625. /**
  1626. * The y-coordinate of top-left corner.
  1627. */
  1628. y: number;
  1629. /**
  1630. * The width in pixels.
  1631. */
  1632. width: number;
  1633. /**
  1634. * The height in pixels.
  1635. */
  1636. height: number;
  1637. }
  1638. export interface StyleCompiler {
  1639. modeName: string;
  1640. styleId: string;
  1641. styleStr: string;
  1642. styleIdentifier: string;
  1643. externalStyles: ExternalStyleCompiler[];
  1644. }
  1645. export interface ExternalStyleCompiler {
  1646. absolutePath: string;
  1647. relativePath: string;
  1648. originalComponentPath: string;
  1649. }
  1650. export interface CompilerModeStyles {
  1651. [modeName: string]: string[];
  1652. }
  1653. export interface CssImportData {
  1654. srcImport: string;
  1655. updatedImport?: string;
  1656. url: string;
  1657. filePath: string;
  1658. altFilePath?: string;
  1659. styleText?: string | null;
  1660. }
  1661. export interface CssToEsmImportData {
  1662. srcImportText: string;
  1663. varName: string;
  1664. url: string;
  1665. filePath: string;
  1666. }
  1667. /**
  1668. * Input CSS to be transformed into ESM
  1669. */
  1670. export interface TransformCssToEsmInput {
  1671. input: string;
  1672. module?: 'cjs' | 'esm' | string;
  1673. file?: string;
  1674. tag?: string;
  1675. encapsulation?: string;
  1676. /**
  1677. * The mode under which the CSS will be applied.
  1678. *
  1679. * Corresponds to a key used when `@Component`'s `styleUrls` field is an object:
  1680. * ```ts
  1681. * @Component({
  1682. * tag: 'todo-list',
  1683. * styleUrls: {
  1684. * ios: 'todo-list.ios.scss',
  1685. * md: 'todo-list.md.scss',
  1686. * }
  1687. * })
  1688. * ```
  1689. * In the example above, two `TransformCssToEsmInput`s should be created, one for 'ios' and one for 'md' (this field
  1690. * is not shared by multiple fields, nor is it a composite of multiple modes).
  1691. */
  1692. mode?: string;
  1693. sourceMap?: boolean;
  1694. minify?: boolean;
  1695. docs?: boolean;
  1696. autoprefixer?: any;
  1697. styleImportData?: string;
  1698. }
  1699. export interface TransformCssToEsmOutput {
  1700. styleText: string;
  1701. output: string;
  1702. map: any;
  1703. diagnostics: Diagnostic[];
  1704. defaultVarName: string;
  1705. styleDocs: StyleDoc[];
  1706. imports: {
  1707. varName: string;
  1708. importPath: string;
  1709. }[];
  1710. }
  1711. export interface PackageJsonData {
  1712. name?: string;
  1713. version?: string;
  1714. main?: string;
  1715. exports?: {
  1716. [key: string]: string | {
  1717. [key: string]: string;
  1718. };
  1719. };
  1720. description?: string;
  1721. bin?: {
  1722. [key: string]: string;
  1723. };
  1724. browser?: string;
  1725. module?: string;
  1726. 'jsnext:main'?: string;
  1727. 'collection:main'?: string;
  1728. unpkg?: string;
  1729. collection?: string;
  1730. types?: string;
  1731. files?: string[];
  1732. ['dist-tags']?: {
  1733. latest: string;
  1734. };
  1735. dependencies?: {
  1736. [moduleId: string]: string;
  1737. };
  1738. devDependencies?: {
  1739. [moduleId: string]: string;
  1740. };
  1741. repository?: {
  1742. type?: string;
  1743. url?: string;
  1744. };
  1745. private?: boolean;
  1746. scripts?: {
  1747. [runName: string]: string;
  1748. };
  1749. license?: string;
  1750. keywords?: string[];
  1751. }
  1752. export interface Workbox {
  1753. generateSW(swConfig: any): Promise<any>;
  1754. generateFileManifest(): Promise<any>;
  1755. getFileManifestEntries(): Promise<any>;
  1756. injectManifest(swConfig: any): Promise<any>;
  1757. copyWorkboxLibraries(wwwDir: string): Promise<any>;
  1758. }
  1759. declare global {
  1760. namespace jest {
  1761. interface Matchers<R, T> {
  1762. /**
  1763. * Compares HTML, but first normalizes the HTML so all
  1764. * whitespace, attribute order and css class order are
  1765. * the same. When given an element, it will compare
  1766. * the element's `outerHTML`. When given a Document Fragment,
  1767. * such as a Shadow Root, it'll compare its `innerHTML`.
  1768. * Otherwise it'll compare two strings representing HTML.
  1769. */
  1770. toEqualHtml(expectHtml: string): void;
  1771. /**
  1772. * Compares HTML light DOM only, but first normalizes the HTML so all
  1773. * whitespace, attribute order and css class order are
  1774. * the same. When given an element, it will compare
  1775. * the element's `outerHTML`. When given a Document Fragment,
  1776. * such as a Shadow Root, it'll compare its `innerHTML`.
  1777. * Otherwise it'll compare two strings representing HTML.
  1778. */
  1779. toEqualLightHtml(expectLightHtml: string): void;
  1780. /**
  1781. * When given an element, it'll compare the element's
  1782. * `textContent`. Otherwise it'll compare two strings. This
  1783. * matcher will also `trim()` each string before comparing.
  1784. */
  1785. toEqualText(expectTextContent: string): void;
  1786. /**
  1787. * Checks if an element simply has the attribute. It does
  1788. * not check any values of the attribute
  1789. */
  1790. toHaveAttribute(expectAttrName: string): void;
  1791. /**
  1792. * Checks if an element's attribute value equals the expect value.
  1793. */
  1794. toEqualAttribute(expectAttrName: string, expectAttrValue: any): void;
  1795. /**
  1796. * Checks if an element's has each of the expected attribute
  1797. * names and values.
  1798. */
  1799. toEqualAttributes(expectAttrs: {
  1800. [attrName: string]: any;
  1801. }): void;
  1802. /**
  1803. * Checks if an element has the expected css class.
  1804. */
  1805. toHaveClass(expectClassName: string): void;
  1806. /**
  1807. * Checks if an element has each of the expected css classes
  1808. * in the array.
  1809. */
  1810. toHaveClasses(expectClassNames: string[]): void;
  1811. /**
  1812. * Checks if an element has the exact same css classes
  1813. * as the expected array of css classes.
  1814. */
  1815. toMatchClasses(expectClassNames: string[]): void;
  1816. /**
  1817. * When given an EventSpy, checks if the event has been
  1818. * received or not.
  1819. */
  1820. toHaveReceivedEvent(): void;
  1821. /**
  1822. * When given an EventSpy, checks how many times the
  1823. * event has been received.
  1824. */
  1825. toHaveReceivedEventTimes(count: number): void;
  1826. /**
  1827. * When given an EventSpy, checks the event has
  1828. * received the correct custom event `detail` data.
  1829. */
  1830. toHaveReceivedEventDetail(eventDetail: any): void;
  1831. /**
  1832. * When given an EventSpy, checks the first event has
  1833. * received the correct custom event `detail` data.
  1834. */
  1835. toHaveFirstReceivedEventDetail(eventDetail: any): void;
  1836. /**
  1837. * When given an EventSpy, checks the last event has
  1838. * received the correct custom event `detail` data.
  1839. */
  1840. toHaveLastReceivedEventDetail(eventDetail: any): void;
  1841. /**
  1842. * When given an EventSpy, checks the event at an index
  1843. * has received the correct custom event `detail` data.
  1844. */
  1845. toHaveNthReceivedEventDetail(index: number, eventDetail: any): void;
  1846. /**
  1847. * Used to evaluate the results of `compareScreenshot()`, such as
  1848. * `expect(compare).toMatchScreenshot()`. The `allowableMismatchedRatio`
  1849. * value from the testing config is used by default if
  1850. * `MatchScreenshotOptions` were not provided.
  1851. */
  1852. toMatchScreenshot(opts?: MatchScreenshotOptions): void;
  1853. }
  1854. }
  1855. }
  1856. export interface MatchScreenshotOptions {
  1857. /**
  1858. * The `allowableMismatchedPixels` value is the total number of pixels
  1859. * that can be mismatched until the test fails. For example, if the value
  1860. * is `100`, and if there were `101` pixels that were mismatched then the
  1861. * test would fail. If the `allowableMismatchedRatio` is provided it will
  1862. * take precedence, otherwise `allowableMismatchedPixels` will be used.
  1863. */
  1864. allowableMismatchedPixels?: number;
  1865. /**
  1866. * The `allowableMismatchedRatio` ranges from `0` to `1` and is used to
  1867. * determine an acceptable ratio of pixels that can be mismatched before
  1868. * the image is considered to have changes. Realistically, two screenshots
  1869. * representing the same content may have a small number of pixels that
  1870. * are not identical due to anti-aliasing, which is perfectly normal. The
  1871. * `allowableMismatchedRatio` is the number of pixels that were mismatched,
  1872. * divided by the total number of pixels in the screenshot. For example,
  1873. * a ratio value of `0.06` means 6% of the pixels can be mismatched before
  1874. * the image is considered to have changes. If the `allowableMismatchedRatio`
  1875. * is provided it will take precedence, otherwise `allowableMismatchedPixels`
  1876. * will be used.
  1877. */
  1878. allowableMismatchedRatio?: number;
  1879. }
  1880. export interface EventSpy {
  1881. events: SerializedEvent[];
  1882. eventName: string;
  1883. firstEvent: SerializedEvent;
  1884. lastEvent: SerializedEvent;
  1885. length: number;
  1886. next(): Promise<{
  1887. done: boolean;
  1888. value: SerializedEvent;
  1889. }>;
  1890. }
  1891. export interface SerializedEvent {
  1892. bubbles: boolean;
  1893. cancelBubble: boolean;
  1894. cancelable: boolean;
  1895. composed: boolean;
  1896. currentTarget: any;
  1897. defaultPrevented: boolean;
  1898. detail: any;
  1899. eventPhase: any;
  1900. isTrusted: boolean;
  1901. returnValue: any;
  1902. srcElement: any;
  1903. target: any;
  1904. timeStamp: number;
  1905. type: string;
  1906. isSerializedEvent: boolean;
  1907. }
  1908. export interface EventInitDict {
  1909. bubbles?: boolean;
  1910. cancelable?: boolean;
  1911. composed?: boolean;
  1912. detail?: any;
  1913. }
  1914. export interface JestEnvironmentGlobal {
  1915. __NEW_TEST_PAGE__: () => Promise<any>;
  1916. __CLOSE_OPEN_PAGES__: () => Promise<any>;
  1917. loadTestWindow: (testWindow: any) => Promise<void>;
  1918. h: any;
  1919. resourcesUrl: string;
  1920. currentSpec?: {
  1921. id?: string;
  1922. description: string;
  1923. fullName: string;
  1924. testPath: string | null;
  1925. };
  1926. env: {
  1927. [prop: string]: string;
  1928. };
  1929. screenshotDescriptions: Set<string>;
  1930. }
  1931. export interface E2EProcessEnv {
  1932. STENCIL_COMMIT_ID?: string;
  1933. STENCIL_COMMIT_MESSAGE?: string;
  1934. STENCIL_REPO_URL?: string;
  1935. STENCIL_SCREENSHOT_CONNECTOR?: string;
  1936. STENCIL_SCREENSHOT_SERVER?: string;
  1937. __STENCIL_EMULATE_CONFIGS__?: string;
  1938. __STENCIL_ENV__?: string;
  1939. __STENCIL_EMULATE__?: string;
  1940. __STENCIL_BROWSER_URL__?: string;
  1941. __STENCIL_APP_SCRIPT_URL__?: string;
  1942. __STENCIL_APP_STYLE_URL__?: string;
  1943. __STENCIL_BROWSER_WS_ENDPOINT__?: string;
  1944. __STENCIL_BROWSER_WAIT_UNTIL?: string;
  1945. __STENCIL_SCREENSHOT__?: 'true';
  1946. __STENCIL_SCREENSHOT_BUILD__?: string;
  1947. __STENCIL_SCREENSHOT_TIMEOUT_MS__?: string;
  1948. __STENCIL_E2E_TESTS__?: 'true';
  1949. __STENCIL_E2E_DEVTOOLS__?: 'true';
  1950. __STENCIL_SPEC_TESTS__?: 'true';
  1951. __STENCIL_PUPPETEER_MODULE__?: string;
  1952. __STENCIL_PUPPETEER_VERSION__?: number;
  1953. __STENCIL_DEFAULT_TIMEOUT__?: string;
  1954. /**
  1955. * Property for injecting transformAliasedImportPaths into the Jest context
  1956. */
  1957. __STENCIL_TRANSPILE_PATHS__?: 'true' | 'false';
  1958. }
  1959. export interface AnyHTMLElement extends HTMLElement {
  1960. [key: string]: any;
  1961. }
  1962. export interface SpecPage {
  1963. /**
  1964. * Mocked testing `document.body`.
  1965. */
  1966. body: HTMLBodyElement;
  1967. /**
  1968. * Mocked testing `document`.
  1969. */
  1970. doc: HTMLDocument;
  1971. /**
  1972. * The first component found within the mocked `document.body`. If a component isn't found, then it'll return `document.body.firstElementChild`.
  1973. */
  1974. root?: AnyHTMLElement;
  1975. /**
  1976. * Similar to `root`, except returns the component instance. If a root component was not found it'll return `null`.
  1977. */
  1978. rootInstance?: any;
  1979. /**
  1980. * Convenience function to set `document.body.innerHTML` and `waitForChanges()`. Function argument should be a HTML string.
  1981. */
  1982. setContent: (html: string) => Promise<any>;
  1983. /**
  1984. * After changes have been made to a component, such as a update to a property or attribute, the test page does not automatically apply the changes. In order to wait for, and apply the update, call `await page.waitForChanges()`.
  1985. */
  1986. waitForChanges: () => Promise<any>;
  1987. /**
  1988. * Mocked testing `window`.
  1989. */
  1990. win: Window;
  1991. build: BuildConditionals;
  1992. flushLoadModule: (bundleId?: string) => Promise<any>;
  1993. flushQueue: () => Promise<any>;
  1994. styles: Map<string, string>;
  1995. }
  1996. /**
  1997. * Options pertaining to the creation and functionality of a {@link SpecPage}
  1998. */
  1999. export interface NewSpecPageOptions {
  2000. /**
  2001. * An array of components to test. Component classes can be imported into the spec file, then their reference should be added to the `component` array in order to be used throughout the test.
  2002. */
  2003. components: any[];
  2004. /**
  2005. * Sets the mocked `document.cookie`.
  2006. */
  2007. cookie?: string;
  2008. /**
  2009. * Sets the mocked `dir` attribute on `<html>`.
  2010. */
  2011. direction?: string;
  2012. /**
  2013. * If `false`, do not flush the render queue on initial test setup.
  2014. */
  2015. flushQueue?: boolean;
  2016. /**
  2017. * The initial HTML used to generate the test. This can be useful to construct a collection of components working together, and assign HTML attributes. This value sets the mocked `document.body.innerHTML`.
  2018. */
  2019. html?: string;
  2020. /**
  2021. * The initial JSX used to generate the test.
  2022. * Use `template` when you want to initialize a component using their properties, instead of their HTML attributes.
  2023. * It will render the specified template (JSX) into `document.body`.
  2024. */
  2025. template?: () => any;
  2026. /**
  2027. * Sets the mocked `lang` attribute on `<html>`.
  2028. */
  2029. language?: string;
  2030. /**
  2031. * Useful for debugging hydrating components client-side. Sets that the `html` option already includes annotated prerender attributes and comments.
  2032. */
  2033. hydrateClientSide?: boolean;
  2034. /**
  2035. * Useful for debugging hydrating components server-side. The output HTML will also include prerender annotations.
  2036. */
  2037. hydrateServerSide?: boolean;
  2038. /**
  2039. * Sets the mocked `document.referrer`.
  2040. */
  2041. referrer?: string;
  2042. /**
  2043. * Manually set if the mocked document supports Shadow DOM or not. Default is `true`.
  2044. */
  2045. supportsShadowDom?: boolean;
  2046. /**
  2047. * When a component is pre-rendered it includes HTML annotations, such as `s-id` attributes and `<!-t.0->` comments. This information is used by client-side hydrating. Default is `false`.
  2048. */
  2049. includeAnnotations?: boolean;
  2050. /**
  2051. * Sets the mocked browser's `location.href`.
  2052. */
  2053. url?: string;
  2054. /**
  2055. * Sets the mocked browser's `navigator.userAgent`.
  2056. */
  2057. userAgent?: string;
  2058. /**
  2059. * By default, any changes to component properties and attributes must `page.waitForChanges()` in order to test the updates. As an option, `autoApplyChanges` continuously flushes the queue on the background. Default is `false`.
  2060. */
  2061. autoApplyChanges?: boolean;
  2062. /**
  2063. * By default, styles are not attached to the DOM and they are not reflected in the serialized HTML.
  2064. * Setting this option to `true` will include the component's styles in the serializable output.
  2065. */
  2066. attachStyles?: boolean;
  2067. /**
  2068. * Set {@link BuildConditionals} for testing based off the metadata of the component under test.
  2069. * When `true` all `BuildConditionals` will be assigned to the global testing `BUILD` object, regardless of their
  2070. * value. When `false`, only `BuildConditionals` with a value of `true` will be assigned to the `BUILD` object.
  2071. */
  2072. strictBuild?: boolean;
  2073. /**
  2074. * Default values to be set on the platform runtime object {@see PlatformRuntime} when creating
  2075. * the spec page.
  2076. */
  2077. platform?: Partial<PlatformRuntime>;
  2078. }
  2079. /**
  2080. * A record of `TypesMemberNameData` entities.
  2081. *
  2082. * Each key in this record is intended to be the path to a file that declares one or more types used by a component.
  2083. * However, this is not enforced by the type system - users of this interface should not make any assumptions regarding
  2084. * the format of the path used as a key (relative vs. absolute)
  2085. */
  2086. export interface TypesImportData {
  2087. [key: string]: TypesMemberNameData[];
  2088. }
  2089. /**
  2090. * A type describing how Stencil may alias an imported type to avoid naming collisions when performing operations such
  2091. * as generating `components.d.ts` files.
  2092. */
  2093. export interface TypesMemberNameData {
  2094. /**
  2095. * The original name of the import before any aliasing was applied.
  2096. *
  2097. * i.e. if a component imports a type as follows:
  2098. * `import { MyType as MyCoolType } from './my-type';`
  2099. *
  2100. * the `originalName` would be 'MyType'. If the import is not aliased, then `originalName` and `localName` will be the same.
  2101. */
  2102. originalName: string;
  2103. /**
  2104. * The name of the type as it's used within a file.
  2105. */
  2106. localName: string;
  2107. /**
  2108. * An alias that Stencil may apply to the `localName` to avoid naming collisions. This name does not appear in the
  2109. * file that is using `localName`.
  2110. */
  2111. importName?: string;
  2112. }
  2113. export interface TypesModule {
  2114. isDep: boolean;
  2115. tagName: string;
  2116. tagNameAsPascal: string;
  2117. htmlElementName: string;
  2118. component: string;
  2119. jsx: string;
  2120. element: string;
  2121. }
  2122. export type TypeInfo = {
  2123. name: string;
  2124. type: string;
  2125. optional: boolean;
  2126. required: boolean;
  2127. internal: boolean;
  2128. jsdoc?: string;
  2129. }[];
  2130. export type ChildType = VNode | number | string;
  2131. export type PropsType = VNodeProdData | number | string | null;
  2132. export interface VNodeProdData {
  2133. key?: string | number;
  2134. class?: {
  2135. [className: string]: boolean;
  2136. } | string;
  2137. className?: {
  2138. [className: string]: boolean;
  2139. } | string;
  2140. style?: any;
  2141. [key: string]: any;
  2142. }
  2143. /**
  2144. * An abstraction to bundle up four methods which _may_ be handled by
  2145. * dispatching work to workers running in other OS threads or may be called
  2146. * synchronously. Environment and `CompilerSystem` related setup code will
  2147. * determine which one, but in either case the call sites for these methods can
  2148. * dispatch to this shared interface.
  2149. */
  2150. export interface CompilerWorkerContext {
  2151. optimizeCss(inputOpts: OptimizeCssInput): Promise<OptimizeCssOutput>;
  2152. prepareModule(input: string, minifyOpts: any, transpile: boolean, inlineHelpers: boolean): Promise<{
  2153. output: string;
  2154. diagnostics: Diagnostic[];
  2155. sourceMap?: SourceMap;
  2156. }>;
  2157. prerenderWorker(prerenderRequest: PrerenderUrlRequest): Promise<PrerenderUrlResults>;
  2158. transformCssToEsm(input: TransformCssToEsmInput): Promise<TransformCssToEsmOutput>;
  2159. }
  2160. /**
  2161. * The methods that are supported on a {@link CompilerWorkerContext}
  2162. */
  2163. export type WorkerContextMethod = keyof CompilerWorkerContext;
  2164. /**
  2165. * A little type guard which will cause a type error if the parameter `T` does
  2166. * not satisfy {@link CPSerializable} (i.e. if it's not possible to cleanly
  2167. * serialize it for message passing via an IPC channel).
  2168. */
  2169. type IPCSerializable<T extends CPSerializable> = T;
  2170. /**
  2171. * A manifest for a job that a worker thread should carry out, as determined by
  2172. * and dispatched from the main thread. This includes the name of the task to do
  2173. * and any arguments necessary to carry it out properly.
  2174. *
  2175. * This message must satisfy {@link CPSerializable} so it can be sent from the
  2176. * main thread to a worker thread via an IPC channel
  2177. */
  2178. export type MsgToWorker<T extends WorkerContextMethod> = IPCSerializable<{
  2179. stencilId: number;
  2180. method: T;
  2181. args: Parameters<CompilerWorkerContext[T]>;
  2182. }>;
  2183. /**
  2184. * A manifest for a job that a worker thread should carry out, as determined by
  2185. * and dispatched from the main thread. This includes the name of the task to do
  2186. * and any arguments necessary to carry it out properly.
  2187. *
  2188. * This message must satisfy {@link CPSerializable} so it can be sent from the
  2189. * main thread to a worker thread via an IPC channel
  2190. */
  2191. export type MsgFromWorker<T extends WorkerContextMethod> = IPCSerializable<{
  2192. stencilId?: number;
  2193. stencilRtnValue: ReturnType<CompilerWorkerContext[T]>;
  2194. stencilRtnError: string | null;
  2195. }>;
  2196. /**
  2197. * A description of a task which should be passed to a worker in another
  2198. * thread. This interface differs from {@link MsgToWorker} in that it doesn't
  2199. * have to be serializable for transmission through an IPC channel, so we can
  2200. * hold things like a `resolve` and `reject` callback to use when the task
  2201. * completes.
  2202. */
  2203. export interface CompilerWorkerTask {
  2204. stencilId: number;
  2205. inputArgs: any[];
  2206. resolve: (val: any) => any;
  2207. reject: (msg: string) => any;
  2208. retries: number;
  2209. }
  2210. /**
  2211. * A handler for IPC messages from the main thread to a worker thread. This
  2212. * involves dispatching an action specified by a {@link MsgToWorker} object to a
  2213. * {@link CompilerWorkerContext}.
  2214. *
  2215. * @param msgToWorker the message to handle
  2216. * @returns the return value of the specified function
  2217. */
  2218. export type WorkerMsgHandler = <T extends WorkerContextMethod>(msgToWorker: MsgToWorker<T>) => ReturnType<CompilerWorkerContext[T]>;
  2219. export interface TranspileModuleResults {
  2220. sourceFilePath: string;
  2221. code: string;
  2222. map: any;
  2223. diagnostics: Diagnostic[];
  2224. moduleFile: Module;
  2225. }
  2226. export interface ValidateTypesResults {
  2227. diagnostics: Diagnostic[];
  2228. dirPaths: string[];
  2229. filePaths: string[];
  2230. }
  2231. export interface TerminalInfo {
  2232. /**
  2233. * Whether this is in CI or not.
  2234. */
  2235. readonly ci: boolean;
  2236. /**
  2237. * Whether the terminal is an interactive TTY or not.
  2238. */
  2239. readonly tty: boolean;
  2240. }
  2241. /**
  2242. * The task to run in order to collect the duration data point.
  2243. */
  2244. export type TelemetryCallback = (...args: any[]) => void | Promise<void>;
  2245. /**
  2246. * The model for the data that's tracked.
  2247. */
  2248. export interface TrackableData {
  2249. arguments: string[];
  2250. build: string;
  2251. component_count?: number;
  2252. config: Config;
  2253. cpu_model: string | undefined;
  2254. duration_ms: number | undefined;
  2255. has_app_pwa_config: boolean;
  2256. os_name: string | undefined;
  2257. os_version: string | undefined;
  2258. packages: string[];
  2259. packages_no_versions?: string[];
  2260. rollup: string;
  2261. stencil: string;
  2262. system: string;
  2263. system_major?: string;
  2264. targets: string[];
  2265. task: TaskCommand | null;
  2266. typescript: string;
  2267. yarn: boolean;
  2268. }
  2269. /**
  2270. * Used as the object sent to the server. Value is the data tracked.
  2271. */
  2272. export interface Metric {
  2273. name: string;
  2274. timestamp: string;
  2275. source: 'stencil_cli';
  2276. value: TrackableData;
  2277. session_id: string;
  2278. }
  2279. export interface TelemetryConfig {
  2280. 'telemetry.stencil'?: boolean;
  2281. 'tokens.telemetry'?: string;
  2282. }
  2283. export {};