@arcgis/lumina-compiler 4.31.0-next.100

package/dist/publicTypes.d.ts

@@ -0,0 +1,626 @@
+import type ts from "typescript";
+import type { Plugin } from "vite";
+import type { build as esbuildBuild } from "esbuild";
+import type { CompilerContext } from "./context";
+import type { Plugin as ManifestPlugin } from "@custom-elements-manifest/analyzer";
+import type { PluginOptions as VitePluginDtsOptions } from "vite-plugin-dts";
+import type { ExternalsOptions as RollupPluginNodeExternalsOptions } from "rollup-plugin-node-externals";
+import type { Options as VsCodeDocOptions } from "custom-element-vs-code-integration";
+import type { Options as JetBrainsDocOptions } from "custom-element-jet-brains-integration";
+import type { ExtendedComponentManifest } from "./manifests/complexTypes/types";
+import type { Module } from "custom-elements-manifest";
+import type { PuppeteerLaunchOptions } from "puppeteer";
+/**
+ * `useLumina()` returns an array of Vite plugins. The array additionally
+ * has a `context` property for accessing the compiler context.
+ */
+export type LuminaPlugins = Plugin[] & {
+    readonly context: CompilerContext;
+};
+/**
+ * Options for controlling the Lumina Compiler.
+ */
+export type LuminaOptions = {
+    /**
+     * Configuration for controlling the build output, dependency externalization
+     * and CDN build process.
+     */
+    readonly build?: BuildOptions;
+    /**
+     * Configurations for controlling the types generation.
+     */
+    readonly types?: GenerateTypesOptions;
+    /**
+     * Configurations for controlling the serve and test environment.
+     */
+    readonly serve?: ServeEnvironmentOptions;
+    /**
+     * Configuration for Puppeteer End-to-End tests.
+     * For more options, see Vite's "testing" option.
+     * This is equivalent to the `e2e` mode in Stencil.
+     *
+     * @remarks
+     * For new projects, we recommend using Vitest browser mode instead of
+     * Puppeteer. See documentation:
+     * https://qawebgis.esri.com/arcgis-components/?path=/docs/references-lumina-testing--docs
+     */
+    readonly puppeteerTesting?: PuppeteerTestingOptions;
+    /**
+     * Configurations for controlling the generation of documentation.
+     */
+    readonly documentation?: GenerateDocumentationOptions;
+    /**
+     * Configurations for controlling the extraction of components metadata and
+     * generation of extra files such as types, docs, and wrappers.
+     *
+     * This is for advanced users who want to customize the generation of metadata
+     * files.
+     */
+    readonly manifests?: GenerateManifestOptions;
+    /**
+     * Configuration for CSS handling.
+     */
+    readonly css?: CssHandlingOptions;
+    /**
+     * Configuration for assets handling.
+     */
+    readonly assets?: AssetHandlingOptions;
+};
+export type BuildOptions = {
+    /**
+     * Configuration for CDN build.
+     */
+    readonly cdn?: BuildCdnOptions;
+    /**
+     * Options for externalizing or bundling in dependencies.
+     */
+    readonly dependencies?: DependencyManagementOptions;
+    /**
+     * Legal comment to add to the top of each entrypoint.
+     * New lines are accepted.
+     * Do not include // or /* - will be added automatically.
+     *
+     * @default require("@arcgis/components-utils").getPreamble()
+     *
+     * @example
+     * ```js
+     * `All material copyright Esri, All Rights Reserved, unless otherwise specified.
+     * See https://js.arcgis.com/{minorVersion}/esri/copyright.txt for details.
+     * v${version}`
+     * ```
+     */
+    readonly preamble?: string;
+    /**
+     * Whether to include source maps even in production builds.
+     * Only set this to true if your library is open source.
+     *
+     * @default false
+     */
+    readonly enableSourceMapsInProduction?: boolean;
+    /**
+     * Wrappers to generate.
+     */
+    readonly wrappers?: WrappersOptions[];
+    readonly ssr?: SsrOptions;
+};
+export type BuildCdnOptions = {
+    /**
+     * Whether to skip CDN build.
+     *
+     * @default false
+     *
+     * @remarks
+     * Even if CDN build is skipped, assets will still be emitted to
+     * dist/cdn-folder-name/assets
+     */
+    readonly skip?: boolean;
+    /**
+     * Determines the CDN folder name and the name of the entrypoint file inside.
+     *
+     * @default "cdn"
+     */
+    readonly namespace?: string;
+    /**
+     * To produce the CDN build, Lumina takes the lazy-loading build of your
+     * package, and post-processes it with ESBuild. You can customize the options
+     * passed to ESBuild.
+     *
+     * @see https://esbuild.github.io/api/#overview
+     */
+    readonly esbuildOptions?: Parameters<typeof esbuildBuild>[0];
+};
+/**
+ * Generic type for the different kinds of wrappers.
+ *
+ * Angular wrappers have been deprecated. See:
+ * https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/1281
+ */
+export type WrappersOptions = React18WrapperOptions;
+export type SsrOptions = {
+    /**
+     * Emit output compatible with Stencil's dist-hydrate-script build.
+     *
+     * @deprecated
+     * This option should be used to smooth the migration path from Stencil.
+     * You should instruct your SSR users to migrate to Lit's SSR implementation,
+     * and then stop using this option.
+     *
+     * @see https://stenciljs.com/docs/hydrate-app
+     * @see https://lit.dev/docs/ssr/overview/
+     */
+    readonly stencilCompatibility?: {
+        /**
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * By default, the hydrate directory is output to package root, outside
+         * of dist.
+         *
+         * @default "hydrate"
+         */
+        path?: string;
+    };
+};
+/**
+ * Options for creating React 18 wrapper.
+ */
+export type React18WrapperOptions = {
+    readonly type: "react18";
+    /**
+     * The file path to the React 18 wrapper proxies file.
+     *
+     * Workflow:
+     * 1. Copy this starter package into your project:
+     *    https://devtopia.esri.com/WebGIS/arcgis-web-components/tree/main/packages/starter-packages/lumina-components-react
+     * 2. Adjust the starter as necessary (package.json, README.md, LICENSE, etc.)
+     * 3. Set this option to the path to the src/components.ts file in the wrapper
+     *    package
+     *
+     * @example
+     * "../lumina-components-react/src/components.ts"
+     */
+    readonly proxiesFile: string;
+};
+/**
+ * Options for externalizing dependencies.
+ *
+ * Reuse the options from rollup-plugin-node-externals, but rename two options for clarity.
+ * - `include` is renamed to `externalize` to make it clear that these are externalized
+ * - `exclude` is renamed to `bundleIn` to make it clear that these are bundled in
+ *
+ * @see https://www.npmjs.com/package/rollup-plugin-node-externals
+ *
+ * @remarks
+ * If Vite is running under Storybook, these options are ignored. This is
+ * because in Storybook build, unlike in a library build, we want to bundle in
+ * all dependencies (with exception of @arcgis/core and web component
+ * dependencies, which are loaded using the ESM CDN).
+ */
+export type DependencyManagementOptions = Omit<RollupPluginNodeExternalsOptions, "exclude" | "include"> & {
+    /**
+     * Force bundle in these dependencies even if they are declared as
+     * dependencies or peerDependencies.
+     *
+     * @example
+     * This is desirable if you wish to control the version of a dependency or
+     * need to post-process the dependency in some way. Usually, you will declare
+     * such as a devDependency, but there is a use case for declaring it as a
+     * dependency instead:
+     *
+     * - If TypeScript types from the bundled in dependencies are referenced in
+     *   the `.d.ts` files of your library, you will need to declare the package
+     *   as a `dependency`, so that it is still installed on the consumer's
+     *   computer so that TypeScript can correctly resolve the types of that
+     *   library.
+     */
+    readonly bundleIn?: NonNullable<RollupPluginNodeExternalsOptions>["exclude"];
+    /**
+     * Force externalize these dependencies, even if they are declared as
+     * devDependencies.
+     *
+     * @example
+     * This is desirable if you are sure the end user will have these dependencies
+     * available, yet do not wish to declare these as devDependencies for some
+     * technical reasons.
+     */
+    readonly externalize?: NonNullable<RollupPluginNodeExternalsOptions>["include"];
+};
+export type ServeEnvironmentOptions = {
+    /**
+     * By default, web component peer dependencies and @arcgis/core are
+     * automatically injected when you are running your package in a test
+     * or serve environment (`npx vite`, `npx vitest`, or storybook serve).
+     *
+     * If some additional web component dependencies are needed in test/serve
+     * environment only, instead of declaring those as peer dependencies, you
+     * should add them as `devDependencies` and list them here to have their
+     * custom elements loaded in the test environment.
+     *
+     * @example
+     * Your package does not depend on `@arcgis/map-components`, but for testing
+     * purposes you wish to load Map Components when testing your package in
+     * `index.html`.
+     * In such case, you can set `extraDependencies: ["@arcgis/map-components"]`
+     */
+    readonly extraDependencies?: string[];
+};
+export type PuppeteerTestingOptions = {
+    /**
+     * @default false
+     */
+    readonly enabled?: boolean;
+    readonly launchOptions?: PuppeteerLaunchOptions;
+};
+export type GenerateDocumentationOptions = {
+    /**
+     * The name of the file to write the custom elements manifest to.
+     *
+     * @default "docs/manifest.json"
+     * @see https://custom-elements-manifest.open-wc.org/
+     */
+    readonly manifestFileName?: string;
+    /**
+     * The name of the file to write the Stencil-like docs JSON to.
+     * For backwards compatibility.
+     *
+     * @default "docs/docs.json"
+     * @see https://stenciljs.com/docs/docs-json
+     */
+    readonly stencilLikeDocsJsonFileName?: string;
+    /**
+     * Provide a URL to a page that documents the component.
+     * This URL will be visible in VS Code and IntelliJ when hovering over a
+     * component tag in an .html file
+     */
+    readonly getComponentDocsUrl?: (tag: string, name: string) => string;
+    /**
+     * Provide a URL to a page that documents the component.
+     * This URL will be visible in VS Code and IntelliJ when hovering over a
+     * component tag in an .html file
+     */
+    readonly getComponentDemoUrl?: (tag: string, name: string) => string;
+    /**
+     * Additional options for the custom-element-vs-code-integration plugin
+     *
+     * @see https://github.com/break-stuff/cem-tools/tree/main/packages/vs-code-integration
+     */
+    readonly vsCode?: VsCodeDocOptions;
+    /**
+     * Additional options for the custom-element-jet-brains-integration plugin
+     *
+     * @see https://github.com/break-stuff/cem-tools/blob/main/packages/jet-brains-integration/README.md
+     */
+    readonly jetBrains?: JetBrainsDocOptions;
+};
+export type GenerateTypesOptions = Omit<VitePluginDtsOptions, "beforeWriteFile" | "strictOutput"> & {
+    /**
+     * A callback for getting reference to the TypeScript Program and TypeScript
+     * host instances created by the compiler.
+     *
+     * @remarks
+     * This will only be called during build, as TypeScript program is not created
+     * when running in serve mode.
+     */
+    readonly typeScriptInstanceCreated?: (program: ts.Program, host: ts.CompilerHost) => void;
+    /**
+     * Allows to modify the content of .d.ts files before they are emitted.
+     *
+     * The .d.ts files are modified as text strings - this is the most performant
+     * and simplest option for less complex transformations.
+     *
+     * Text transformers run after AST transformers.
+     */
+    readonly declarationTextTransformers?: DeclarationTextTransformer[];
+    /**
+     * Allows to modify the content of .d.ts files before they are emitted.
+     *
+     * The .d.ts files are modified as TypeScript AST nodes - this is useful for
+     * advanced transformations.
+     *
+     * AST transformers run before text transformers.
+     *
+     * @remarks
+     * This transformer is used only on .d.ts files of your components. Any
+     * .d.ts files for utility files or other non-entrypoint files are not
+     * affected by this transformer. For those, you can use the
+     * `declarationAstTransformers` option.
+     */
+    readonly declarationAstTransformers?: FileTransformer[];
+    /**
+     * Allows to modify the .tsx files as TypeScript AST nodes before they are
+     * emitted.
+     *
+     * This is useful for advanced transformations.
+     *
+     * @remarks
+     * It is advisable that your transformer preserves as many of the original
+     * source file nodes as possible as that will help in source map generation.
+     * Thus where possible, instead of using ts.factory.create* functions, use
+     * the ts.factory.update* functions.
+     *
+     * @remarks
+     * Any changes done in this transformer will not affect the generated typings.
+     * If you wish your changes to apply to typings too, you will need to
+     * implement a separate typings transformer
+     *
+     * @remarks
+     * If you wish to modify the code as a text string rather than AST, then add
+     * a Vite plugin to your vite.config.ts that will implement a transform()
+     * hook. In such case, do not forget to generate a source map for your changes.
+     * See https://rollupjs.org/plugin-development/#source-code-transformations
+     */
+    readonly sourceFileTransformers?: FileTransformer[];
+};
+export type DeclarationTextTransformer = (original: DeclarationFile, context: CompilerContext) => DeclarationFile | false;
+export type DeclarationFile = {
+    filePath: string;
+    content: string;
+};
+/**
+ * @example
+ * ```ts
+ * (sourceFile, context) =>
+ *   context.fileManifest === undefined || !sourceFile.text.includes("@method")
+ *    ? sourceFile.statements
+ *    : sourceFile.statements.map((statement) =>
+ *        statementVisitor(statement, context)
+ *      );
+ * ```
+ */
+export type FileTransformer = (sourceFile: ts.SourceFile, context: FileTransformContext) => readonly ts.Statement[];
+export type FileTransformContext = {
+    readonly compiler: CompilerContext;
+    readonly transformation: ts.TransformationContext;
+    /**
+     * The custom element manifest for this file.
+     * if this file did not define any components, then this will be undefined.
+     */
+    readonly fileManifest: Module | undefined;
+};
+/**
+ * @see https://custom-elements-manifest.open-wc.org/
+ */
+export type GenerateManifestOptions = {
+    /**
+     * Additional plugins to use when creating the manifest.
+     * This is useful if you want to add additional metadata or customize how
+     * your component structure is analyzed
+     *
+     * @example
+     * You can write a plugin that will automatically add JSDoc for some
+     * "well known" properties if JSDoc is not explicitly present in the code.
+     */
+    readonly plugins?: ManifestPlugin[];
+    /**
+     * This function will be called after the manifest is created but before it is
+     * used to generate any output files.
+     *
+     * You can mutate the manifest to affect the typings, lazy component metadata
+     * and documentation.
+     */
+    readonly afterManifestCreate?: (manifest: ExtendedComponentManifest) => void;
+};
+export type CssHandlingOptions = {
+    /**
+     * Path to a styles file that you wish to be applied to the entire page, even
+     * outside the shadow dom. Useful for declaring CSS variables.
+     *
+     * These styles will be applied automatically in the CDN build, thus users
+     * do not need a separate `<link>` tag. In the NPM build, users will need to
+     * manually apply these styles as appropriate in their bundler (either via
+     * import statement, or via `<link>` tag or etc).
+     */
+    globalStylesPath?: string;
+    /**
+     * Styles that you wish to make available in each component's shadow root, but
+     * to not apply outside the shadow root.
+     *
+     * These styles do no apply to non-shadow-root components.
+     *
+     * @remarks
+     * If you are using SCSS, you can also use the following Vite config option to
+     * add a common SCSS import to every SCSS file:
+     * ```tsx
+     * css: {
+     *   preprocessorOptions: {
+     *     scss: {
+     *       // Add "includes.scss" import to each scss file
+     *       additionalData(code, id) {
+     *         const commonCss = "/src/assets/styles/includes";
+     *         if (!id.endsWith(".scss") || id.endsWith(`${commonCss}.sass`)) {
+     *           return undefined;
+     *         }
+     *         return `@import "${commonCss}";\n${code}`;
+     *       },
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    commonStylesPath?: string;
+    /**
+     * The attribute that indicates a component has rendered it's content.
+     * Usually this attribute is added after your component's `loaded()` lifecycle
+     * happened. However, during SSR, "hydrated" is added right away on the
+     * server.
+     *
+     * Until element has this attribute, it will have `visibility:hidden` style
+     * applied.
+     *
+     * @default "hydrated"
+     */
+    hydratedAttribute?: string;
+    /**
+     * By default, if a side effect CSS import is detected, an error will thrown.
+     * This is due to the requirement of handling shadow DOM styling.
+     * Instead, you should import the "styles" variable from the .css file and add
+     * it to your component.
+     *
+     * If there is a side effect CSS import from a file you don't control (i.e a
+     * library you are using), then assign this property to a function that would
+     * return "drop" to ignore those imports. In such case, you will be
+     * responsible for manually providing the styles to the web component.
+     *
+     * If neither of these is satisfactory, a more complex solution can be
+     * implemented in the future.
+     *
+     * @remarks
+     * In regular codebases, it's common to have an import statement like so:
+     * ```ts
+     * import 'some-library/styles.css';
+     * ```
+     *
+     * Doing so in a web component codebase is a bit trickier as the styles
+     * need to be attached not to the `<head>` of the page, but to the shadow
+     * root of the component that imported it. Doing so for transitive imports
+     * is even trickier (if your component imported a .js file, which in turn
+     * imported a .css file) as dependency tracking becomes necessary.
+     *
+     * That is why, for now, css imports need to be handled like so:
+     *
+     * - If import is originating from a file you control (your component file),
+     *   import the "styles" variable from the css file:
+     *
+     *   ```ts
+     *   import { styles } from 'some-library/styles.css';
+     *   ```
+     *
+     *   And then add it to your component
+     *
+     *   ```ts
+     *   export class MyComponent extends LitElement {
+     *     static override styles = styles;
+     *   }
+     *   ```
+     *
+     * - If the import is originating from a file you don't control (i.e a library
+     *   code), you have to set this property to a function that will return
+     *   "drop" for a given library import to ignore such import, and then you
+     *   will have to manually provide the CSS file by importing "styles"
+     *   variable.
+     *
+     * @default () => "throwError"
+     *
+     */
+    readonly sideEffectImportHandling?: (specifier: string, importer: string) => "drop" | "throwError";
+};
+export type AssetHandlingOptions = {
+    /**
+     * Any additional assets you wish to provide, besides those located in the
+     * assets/ directories
+     *
+     * @remarks
+     * If you need additional flexibility, you can call the
+     * `compilerContext.provideAssets()` utility at any time
+     *
+     * ```ts
+     * // vite.config.ts
+     * import { defineConfig } from "vite";
+     * import { useLumina } from "@arcgis/lumina-compiler";
+     *
+     * export default defineConfig((env) => {
+     *   const lumina = useLumina();
+     *
+     *   lumina.context.provideAssets([
+     *     {
+     *       type: "dynamic",
+     *       source: () => new Date().toString(),
+     *       destination: "build_date.txt",
+     *     },
+     *   ]);
+     *
+     *   return {
+     *     plugins: [lumina],
+     *   };
+     * });
+     * ```
+     */
+    readonly extra?: (AssetSpec | ProvideAssetsOptions)[];
+    /**
+     * The default asset path to use in NPM and CDN builds.
+     *
+     * @default require("@arcgis/lumina-compiler").inferCdnUrl()
+     */
+    readonly defaultPath?: string;
+    /**
+     * Asset transformers to apply to assets in the assets/ directories in each
+     * component and to the assets/ directory in the package root.
+     *
+     * @example
+     * Example use cases:
+     * - minify the assets in production builds
+     * - transform the asset files
+     * - throw errors if detected incorrect assets
+     */
+    readonly transformers?: AssetTransformer[];
+};
+/**
+ * Provide additional assets to be copied to the output directory during build
+ * or served during development.
+ */
+export type ProvideAssetsOptions = {
+    readonly assets: AssetSpec[];
+    readonly transformers?: AssetTransformer[];
+    /**
+     * By default, provided assets are available both to the dev server and are
+     * written to dist/
+     * You can optionally configure to only apply the assets to the dev server or
+     * only to the build.
+     */
+    readonly apply?: CompilerContext["viteCommand"];
+};
+export type AssetSpec = AssetDirectory | AssetDynamic | AssetFile;
+type AssetDirectory = {
+    readonly type: "directory";
+    /**
+     * @example src/components/root/assets
+     */
+    readonly source: string;
+    /**
+     * Base directory is /dist/cdn-folder-name/assets
+     *
+     * @example /root
+     * @example ../some-folder-outside-assets-dir/
+     */
+    readonly destination: string;
+};
+type AssetFile = {
+    readonly type: "file";
+    /**
+     * @example docs.json
+     */
+    readonly source: string;
+    /**
+     * Base directory is /dist/cdn-folder-name/assets
+     *
+     * @example docs.json
+     */
+    readonly destination: string;
+};
+type AssetDynamic = {
+    readonly type: "dynamic";
+    /**
+     * @example () => new Date().toString()
+     */
+    readonly source: () => Promise<string> | string;
+    readonly destination: string;
+};
+/**
+ * Transform static assets before serving then in development or before writing
+ * them to dist/ in production.
+ * Example use case: minifying JSON files, compressing SVGs, compressing images.
+ *
+ * @remarks
+ * Both in build and serve mode, the destination will be an absolute path to a
+ * file in the dist/ directory. The path will use POSIX path separators.
+ */
+export type AssetTransformer = {
+    readonly match: (destination: string, context: CompilerContext) => boolean;
+    /**
+     * Assuming for now that transformer will transform text files only.
+     * Also, for now only the first matching transformer will be used.
+     */
+    readonly transform: (fileContent: string, destination: string, context: CompilerContext) => string;
+};
+export {};

package/dist/puppeteer-testing/globalSetup.d.ts

@@ -0,0 +1,72 @@
+import type { GlobalSetupContext } from "vitest/dist/node.js";
+import { type ConnectOptions } from "puppeteer";
+declare module "vitest" {
+    interface ProvidedContext {
+        isDevToolsEnabled?: boolean;
+        isHeadlessBrowser?: boolean;
+        devServerHtml?: string;
+        devServerUrl?: string;
+        puppeteerConnectOptions?: ConnectOptions;
+    }
+}
+/**
+ * Global setup file for Vitest Puppeteer integration.
+ *
+ * This is run once, in the main thread, before any tests are run.
+ *
+ * We start browser via Puppeteer so that tests can render to it and interact
+ * with it.
+ *
+ * In the browser, we render the test suite. The browser sends requests for
+ * JavaScript files to the Vite dev server.
+ *
+ * We start that Vite dev server in this file too. It is separate from the
+ * Vite dev server started by Vitest.
+ *
+ * It has to be separate because Vitest's dev server resolves imports for the
+ * "node" import condition. If we instead tell Vitest to use browser export
+ * conditions, than Lit's "isServer" will be false both in browser and node.js,
+ * potentially breaking some components. While happy-dom is neat, it does match
+ * the actual browser API 100%. It is safer to run a separate Vite instance for
+ * Node.js (Vitest) and browser. This is a short-term issue anyway as we are
+ * looking to moving to Vitest browser mode feature, that would resolve this
+ * issue.
+ *
+ * Here is an example Vite configuration plugin that is needed if you wish to
+ * make Vitest's Vite instance somewhat usable directly by Playwright's browser:
+ * ```ts
+ * config: (config) => {
+ *   const conditions = config.resolve?.conditions;
+ *   // Remove "node" condition.
+ *   // Can't do this imperatively as Vite's default configuration merging only
+ *   // allows adding settings, not removing.
+ *   if (conditions && conditions.includes("node")) {
+ *     conditions.splice(conditions.indexOf("node"), 1);
+ *   }
+ *   return {
+ *     server: {
+ *       middlewareMode: false,
+ *     },
+ *     test: {
+ *       api: true,
+ *       environment: "happy-dom",
+ *     },
+ *   };
+ * },
+ *
+ * Vite's upcoming Environment API will make it possible to use a single dev
+ * server (https://github.com/vitejs/vite/pull/16089/files). However, we plan
+ * to provide Puppeteer integration only temporary to ease the Stencil
+ * migration, so optimizing it too much is not a goal.
+ */
+export declare function setup(context: GlobalSetupContext): Promise<() => Promise<void>>;
+export type PuppeteerViteGlobals = {
+    /**
+     * Helps lumina-compiler dev server know that is it running for Puppeteer
+     * browser.
+     *
+     * Not exposing this in global typings for usage in tests because
+     * `import.meta.env.MODE` should be used instead.
+     */
+    __IS_IN_PUPPETEER__?: true;
+};