@arcgis/lumina-compiler 5.2.0-next.2 → 5.2.0-next.21

package/dist/options.d.ts

@@ -0,0 +1,675 @@
+import type ts from "typescript";
+import type { Plugin } from "vite";
+import type { build as esbuildBuild } from "esbuild";
+import type { CompilerContext } from "./context/index.js";
+import type { WebTypesOptions } from "./docs/webTypes/types.js";
+import type { VsCodeDocOptions } from "./docs/vsCodeCustomData/types.js";
+import type { DependencyManagementOptions as BaseDependencyManagementOptions } from "@arcgis/components-build-utils";
+import type { ApiExtractorPluginConfig } from "@arcgis/api-extractor/vite/plugin";
+import type { ResolvedApiExtractorConfig } from "@arcgis/api-extractor/extractor/config";
+import type { CopyDocDefinitions } from "@arcgis/api-extractor/extractor/extractors/copyDoc";
+import type { ApiJson, ApiModule } from "@arcgis/api-extractor/apiJson";
+
+/**
+ * `useLumina()` returns an array of Vite plugins. The array additionally
+ * has a `context` property for accessing the compiler context.
+ */
+export interface LuminaPlugins extends Array<Plugin> {
+  readonly context: CompilerContext;
+}
+
+/** Options for controlling the Lumina Compiler. */
+export interface 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.
+   *
+   * @deprecated
+   * For new projects, use Vitest browser mode instead of Puppeteer.
+   * See documentation: https://webgis.esri.com/references/lumina/testing
+   */
+  readonly puppeteerTesting?: PuppeteerTestingOptions;
+  /** Configurations for controlling the generation of documentation. */
+  readonly documentation?: GenerateDocumentationOptions;
+  readonly apiExtractor?: ApiExtractorPluginConfig;
+  /**
+   * 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 apiJson?: ApiJsonOptions;
+  /** Configuration for CSS handling. */
+  readonly css?: CssHandlingOptions;
+  /** Configuration for assets handling. */
+  readonly assets?: AssetHandlingOptions;
+  readonly linting?: LintingOptions;
+  /** @deprecated See https://discord.com/channels/1012791295170859069/1047015641225371718 */
+  readonly experimental?: { readonly stabilizeRef?: boolean; };
+}
+
+export interface BuildOptions {
+  /** Configuration for CDN build. */
+  readonly cdn?: BuildCdnOptions;
+  /** @deprecated Use Storybook build or separate test app package. */
+  readonly webApp?: BuildWebAppOptions;
+  /** 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/toolkit/string").getPreamble()
+   * @example
+   * ```js
+   * `COPYRIGHT Esri - https://js.arcgis.com/{minorVersion}/LICENSE.txt`
+   * ```
+   */
+  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.
+   *
+   * @deprecated Wrappers will be dropped in 6.0
+   */
+  readonly wrappers?: WrappersOptions[];
+}
+
+export interface 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;
+  /**
+   * @deprecated
+   * To improve CDN experience and simplify redirect handling,
+   * deprecated namespace to use consistent CDN folder and file names.
+   *
+   * Reference: https://devtopia.esri.com/WebGIS/arcgis-web-components/issues/5051#issuecomment-5482327
+   *
+   * 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 dist/loader.js file and
+   * and post-processes it with ESBuild to make it ready for consumption in the
+   * browser.
+   *
+   * You can customize the options passed to ESBuild. Note, some options may
+   * conflict with the Lumina build process.
+   *
+   * @see https://esbuild.github.io/api/#overview
+   */
+  readonly esbuildOptions?: Parameters<typeof esbuildBuild>[0];
+  /**
+   * Transform the CDN entrypoint before it is processed by ESBuild.
+   *
+   * This callback is for advanced use cases only. The build output may change
+   * between Lumina versions without prior notice.
+   *
+   * @param code
+   * @param context
+   */
+  entrypointTransformer?(code: string, context: CompilerContext): string;
+  /**
+   * A callback for mutating CDN ESBuild output chunks before they are written
+   * to disk.
+   * This callback is for advanced use cases only. The build output may change
+   * between Lumina versions without prior notice. Using this callback may
+   * corrupt the CDN source map if it is enabled.
+   *
+   * @param chunks
+   * @param context
+   */
+  transformer?(chunks: Map<string, CdnChunk>, context: CompilerContext): void;
+}
+
+/** @deprecated Use Storybook build or separate test app package. */
+export interface BuildWebAppOptions {
+  /**
+   * If set, will produce a web app build, based on index.html files and
+   * cdn build.
+   *
+   * @deprecated Use Storybook build or a separate test app package.
+   * @default undefined
+   * @example "www"
+   * @see [Based on Stencil's www build](https://stenciljs.com/docs/www)
+   */
+  readonly destination?: string;
+  /**
+   * @deprecated Use Storybook build or a separate test app package.
+   * @param htmlContent
+   * @param htmlFilePath
+   * @param context
+   */
+  transformFile?(htmlContent: string, htmlFilePath: string, context: CompilerContext): string;
+  /**
+   * @deprecated Use Storybook build or a separate test app package.
+   * @param context
+   */
+  afterBuildEnd?(context: CompilerContext): Promise<void> | void;
+}
+
+export interface CdnChunk {
+  code: string;
+  /**
+   * Whether chunk is currently being processed. Used to detect cyclical imports.
+   *
+   * @internal
+   */
+  isProcessing: boolean;
+  isAsync?: boolean;
+  oldSingleExportName?: string;
+}
+
+/**
+ * Generic type for the different kinds of wrappers.
+ *
+ * Angular wrappers have been deprecated. See:
+ * https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/1281
+ *
+ * @deprecated Wrappers will be dropped in 6.0
+ */
+export type WrappersOptions = React18WrapperOptions;
+
+/**
+ * Options for creating React 18 wrapper.
+ *
+ * Documentation: https://webgis.esri.com/references/lumina/build#build-wrappers
+ *
+ * @deprecated Wrappers will be dropped in 6.0
+ */
+export interface React18WrapperOptions {
+  /** @deprecated Wrappers will be dropped in 6.0 */
+  readonly type: "react18";
+  /**
+   * The file path to the React 18 wrapper proxies file.
+   *
+   * @example "../lumina-components-react/src/components.ts"
+   */
+  readonly proxiesFile: string;
+}
+
+/**
+ * Options for externalizing dependencies.
+ *
+ * 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 interface DependencyManagementOptions extends BaseDependencyManagementOptions {
+  /**
+   * By default, Lumina will error if it encounters usage of an unknown custom
+   * element. This setting allows to silence such error if you are manually
+   * importing some custom elements.
+   *
+   * > [!IMPORTANT]
+   * >
+   * > This option is an escape hatch. Build-time optimizations are not applied
+   * > to such custom elements. Additionally, you assume the responsibility for
+   * > correctly loading the web component in lazy, non-lazy and CDN builds.
+   *
+   * @param tagName
+   * @param fileName
+   * @param context
+   * @example
+   * ```ts
+   * // Silence errors for unknown custom elements that start with "fluent-"
+   * silenceUnknownJsxElementUsage: (tagName) => tagName.startsWith("fluent-")
+   * ```
+   */
+  silenceUnknownJsxElementUsage?(tagName: string, fileName: string, context: CompilerContext): boolean;
+}
+
+export interface 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?: (DetailedExtraDependency | string)[];
+}
+
+export interface DetailedExtraDependency {
+  /** @example "@arcgis/map-config-components" */
+  readonly name: string;
+  /**
+   * Overwrite the default CDN asset path for this dependency.
+   *
+   * @param context
+   * @example (): string => `https://example.com/arcgis-components/builds/main/cdn/map-config-components/`
+   */
+  getCdnUrl(context: CompilerContext): string;
+}
+
+/**
+ * @deprecated
+ * For new projects, use Vitest browser mode instead of Puppeteer.
+ * See documentation: https://webgis.esri.com/references/lumina/testing
+ */
+export interface PuppeteerTestingOptions {
+  /**
+   * @deprecated
+   * For new projects, use Vitest browser mode instead of Puppeteer.
+   * See documentation: https://webgis.esri.com/references/lumina/testing
+   * @default false
+   */
+  readonly enabled?: boolean;
+  /**
+   * Additional number of milliseconds to wait in each `page.waitForChanges()`
+   * call after all components re-rendered. The default in Stencil was `100ms`.
+   * Setting this to `false` will speed up the tests.
+   *
+   * @default 0
+   */
+  readonly waitForChangesDelay?: number;
+  /**
+   * @example
+   * ```ts
+   * import type { LaunchOptions } from "puppeteer";
+   * // ...
+   *   launchOptions: {
+   *     args: ["--no-sandbox", "--disable-setuid-sandbox"],
+   *   } satisfies LaunchOptions;
+   * ```
+   */
+  readonly launchOptions?: Record<string, unknown>;
+}
+
+export interface GenerateDocumentationOptions {
+  /** @deprecated Create "api-extractor.config.ts" and use `documentation.copyDocDefinitions` instead. [Example config](https://webgis.esri.com/references/api-extractor/tags-reference#copydoc)). */
+  readonly copyDefinitions?: CopyDocDefinitions;
+  /** @deprecated Create "api-extractor.config.ts" and use `context.apiJsonEmitPath` instead. [Example config](https://webgis.esri.com/references/api-extractor/running-standalone)). */
+  readonly apiJsonFileName?: string | false;
+  /**
+   * The name of the file to write the Stencil-like docs JSON to.
+   * For backwards compatibility.
+   *
+   * @deprecated Use api.json instead.
+   * @default "docs/docs.json"
+   * @see https://stenciljs.com/docs/docs-json
+   */
+  readonly stencilLikeDocsJsonFileName?: string | false;
+  /** @deprecated Create "api-extractor.config.ts" and use `documentation.publicStoryUrlPrefix` instead. [Example config](https://webgis.esri.com/references/api-extractor/running-standalone)). */
+  readonly publicStoryUrlPrefix?: string;
+  /**
+   * @deprecated Create "api-extractor.config.ts" and use `documentation.getComponentDocsUrl` instead. [Example config](https://webgis.esri.com/references/api-extractor/running-standalone)).
+   * @param tagName
+   * @param className
+   */
+  getComponentDocsUrl?(tagName: string, className: string): string | undefined;
+  /**
+   * @deprecated Create "api-extractor.config.ts" and use `documentation.getComponentDemoUrl` instead. [Example config](https://webgis.esri.com/references/api-extractor/running-standalone)).
+   * @param tagName
+   * @param className
+   */
+  getComponentDemoUrl?(tagName: string, className: string): string | undefined;
+  /**
+   * Additional options for web component documentation for VS Code. This
+   * documentation provides intellisense when editing .html and .css files.
+   *
+   * @see https://devtopia.esri.com/WebGIS/arcgis-web-components/issues/1226
+   */
+  readonly vsCode?: VsCodeDocOptions | false;
+  /**
+   * Additional options for the web-types.json generation
+   *
+   * @see https://github.com/JetBrains/web-types
+   */
+  readonly jetBrains?: WebTypesOptions | false;
+}
+
+export interface GenerateTypesOptions {
+  /** @deprecated Create "api-extractor.config.ts" and use `types.compilerOptions` instead. [Example config](https://webgis.esri.com/references/api-extractor/tags-reference#copydoc)). */
+  readonly compilerOptions?: ResolvedApiExtractorConfig["types"]["compilerOptions"];
+  /** @deprecated Create "api-extractor.config.ts" and use `types.typeScriptConfigPath` instead. [Example config](https://webgis.esri.com/references/api-extractor/tags-reference#copydoc)). */
+  readonly tsconfigPath?: string;
+  /**
+   * @deprecated Create "api-extractor.config.ts" and use `types.afterDiagnostic` instead. [Example config](https://webgis.esri.com/references/api-extractor/tags-reference#copydoc)).
+   * @param diagnostics
+   */
+  afterDiagnostic?(diagnostics: readonly ts.Diagnostic[]): Promise<void> | void;
+  /**
+   * @deprecated Create "api-extractor.config.ts" and use `types.typeScriptInstanceCreated` instead. [Example config](https://webgis.esri.com/references/api-extractor/tags-reference#copydoc)).
+   * @param program
+   * @param host
+   */
+  typeScriptInstanceCreated?(program: ts.Program, host: ts.CompilerHost): void;
+  /** @deprecated Create "api-extractor.config.ts" and use `types.declarationTextTransformers` instead. [Example config](https://webgis.esri.com/references/api-extractor/tags-reference#copydoc)). */
+  readonly declarationTextTransformers?: DeclarationTextTransformer[];
+  /**
+   * Allows to modify the .tsx files as TypeScript AST nodes before they are
+   * emitted.
+   *
+   * This is useful for advanced transformations.
+   *
+   * 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.
+   *
+   * 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
+   *
+   * 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[];
+}
+
+/**
+ * @param original
+ * @param context
+ * @deprecated
+ */
+export type DeclarationTextTransformer = (original: DeclarationFile, context: CompilerContext) => DeclarationFile | false;
+
+/** @deprecated */
+export interface DeclarationFile {
+  filePath: string;
+  content: string;
+}
+
+/**
+ * @param sourceFile
+ * @param context
+ * @example
+ * ```ts
+ * (sourceFile, context) =>
+ *   context.apiModule === 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 interface FileTransformContext {
+  readonly compiler: CompilerContext;
+  readonly transformation: ts.TransformationContext;
+  /**
+   * The api.json for this file.
+   * if this file did not define any components, then this will be undefined.
+   */
+  readonly apiModule?: ApiModule;
+}
+
+/** @deprecated */
+export interface ApiJsonOptions {
+  /**
+   * @deprecated Create "api-extractor.config.ts" and use `afterCreate` instead. [Example config](https://webgis.esri.com/references/api-extractor/tags-reference#copydoc)).
+   * @param api
+   * @param isPatchOnly
+   */
+  afterCreate?(api: ApiJson, isPatchOnly: boolean): void;
+}
+
+export interface 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).
+   *
+   * @example
+   * // If relative path is provided, it is relative to the root directory.
+   * "./src/styles/global.css"
+   */
+  readonly 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.
+   *
+   * 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}`;
+   *       },
+   *     },
+   *   },
+   * }
+   * ```
+   */
+  readonly 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"
+   */
+  readonly hydratedAttribute?: string;
+}
+
+export interface AssetHandlingOptions {
+  /**
+   * Any additional assets you wish to provide, besides those located in the
+   * assets/ directories.
+   *
+   * @example
+   * ```ts
+   * import resolvePkg from "resolve-pkg";
+   *
+   * // ...
+   *
+   * extra: [
+   *   {
+   *     type: "directory",
+   *     source: resolvePkg("@arcgis/arcade-sdk/dist/arcgis-arcade-editor")!,
+   *     destination: "arcade-language",
+   *   },
+   * ]
+   * ```
+   * @example
+   * 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 interface 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;
+
+export interface 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;
+}
+
+export interface AssetFile {
+  readonly type: "file";
+  /** @example docs.json */
+  readonly source: string;
+  /**
+   * Base directory is /dist/cdn-folder-name/assets
+   *
+   * @example docs.json
+   */
+  readonly destination: string;
+}
+
+export interface AssetDynamic {
+  readonly type: "dynamic";
+  /** @example () => new Date().toString() */
+  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.
+ *
+ * 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 interface AssetTransformer {
+  /**
+   * @param destination
+   * @param context
+   */
+  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.
+   *
+   * @param fileContent
+   * @param destination
+   * @param context
+   */
+  transform(fileContent: string, destination: string, context: CompilerContext): string;
+}
+
+export interface LintingOptions {
+  /**
+   * Lumina includes build-time checks for common issues and possible bugs.
+   * Most of those should be immediately addressable. However, some (like
+   * updating default value for boolean properties) may require a breaking
+   * change.
+   *
+   * This option exists to temporarily turn these errors into warnings.
+   *
+   * @example
+   * To silence an error in a file, add an entry like the following with the
+   * relative path to the file:
+   *
+   * ```ts
+   * booleanMustDefaultFalse: ["src/components/counter/counter.tsx"]
+   * ```
+   */
+  readonly silence: LintingSilenceOptions;
+}
+
+export interface LintingSilenceOptions {
+  /**
+   * Lumina components may declare required properties using `@required` JSDoc
+   * tag.
+   *
+   * Required properties are enforced in public TypeScript typings. However,
+   * they are not enforced by TypeScript within the package itself due to
+   * technical limitations. Instead, this rule exists to enforce them at
+   * build-time.
+   *
+   * [Documentation](https://webgis.esri.com/references/lumina/properties#string-properties)
+   */
+  mustIncludeAllRequiredProperties?: string[];
+}