@arcgis/lumina-compiler 5.2.0-next.1 → 5.2.0-next.100

package/LICENSE.md

@@ -1,12 +1,14 @@
 # Licensing
 
-COPYRIGHT © Esri
+COPYRIGHT Esri
 
 All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.
 
-This material is licensed for use under the [Esri Master License Agreement (MLA)](https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf), and is bound by the terms of that agreement.
+This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement.
 You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
 
+See use restrictions at https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf.
+
 For additional information, contact:
 Environmental Systems Research Institute, Inc.
 Attn: Contracts and Legal Services Department

package/README.md

@@ -8,5 +8,5 @@ It is not intended to be used directly, but rather used as a dependency by other
 
 ## License
 
-This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package, and at https://js.arcgis.com/5.1/LICENSE.txt.
-For third party notices, see https://js.arcgis.com/5.1/third-party-notices.txt.
+This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package, and at https://js.arcgis.com/5.2/LICENSE.txt.
+For third party notices, see https://js.arcgis.com/5.2/third-party-notices.txt.

package/dist/context/index.d.ts

@@ -1,296 +1,167 @@
-import { ConfigEnv, Plugin, ResolvedConfig, ViteDevServer } from 'vite';
-import { default as ts } from 'typescript';
-import { ApiCustomElementDeclaration, ApiJson } from '@arcgis/api-extractor/apiJson';
-import { LuminaOptions, AssetSpec, AssetTransformer, ProvideAssetsOptions, LintingOptions } from '../publicTypes.ts';
-import { DocsType } from '../docs/types.ts';
-import { ContextDirectories } from './types.ts';
-import { makeLoaders, computeServeOnlyDependencies } from '../dependencies/loaders.ts';
-import { CustomElementInterdependencies } from '../entrypoints/config.ts';
-import { getLocalDefinedComponentsFromApiJson } from '../entrypoints/resolveTagName.ts';
-import { unsafeGetUndocumentedPrinter } from '@arcgis/api-extractor/utils/internalTypeScriptApis';
-import { ApiExtractor } from '@arcgis/api-extractor/extractor/ApiExtractor';
-import { ApiExtractorPluginConfig } from '@arcgis/api-extractor/vite/plugin';
-/**
- * A compiler state and context object that is shared across plugins.
- */
-export declare class CompilerContext {
-    /**
-     * TypeScript source file instances created in serve mode
-     *
-     * @private
-     */
-    private readonly _typeScriptSourceFiles;
-    /**
-     * A promise for after tsconfig.json and api-extractor.config.ts are loaded
-     * and list of files in current project are resolved.
-     *
-     * @private
-     */
-    configsPromise: Promise<void>;
-    /**
-     * Whether minification is enabled for transformed JSX (lit-html templates)
-     * and generated component code.
-     */
-    shouldMinify: boolean;
-    /**
-     * Like this.shouldMinify, but true when in test mode. Reasons:
-     * - If accessing .textContent, the whitespace amount differs between minified
-     *   and non-minified lit-html templates. In Stencil's JSX this was not the
-     *   case. To ease migration of tests, we minify lit-html in tests too.
-     * - From the above, you can see that minification does change semantics in
-     *   some cases. To have tests be truer to the real world, we minify in tests.
-     *
-     * Also, true during build as per
-     * https://devtopia.esri.com/WebGIS/arcgis-web-components/issues/2084
-     */
-    shouldMinifyJsx: boolean;
-    /**
-     *
-     * A vite plugin that sets the initial context information based on Vite
-     * environment
-     *
-     * @private
-     */
-    readonly _plugin: Plugin;
-    /**
-     * List of directories of common interest to the compiler
-     */
-    dir: ContextDirectories;
-    apiExtractor: ApiExtractor | undefined;
-    /**
-     * @private
-     */
-    apiExtractorPluginConfig: ApiExtractorPluginConfig;
-    /**
-     * The api.json stores information about the structure of all components in
-     * the package (their properties, methods, events, JSDoc and etc).
-     *
-     * You can augment the api.json generation using the `apiJson` option in
-     * `useLumina()`
-     */
-    apiJson: ApiJson;
-    /**
-     * A flattened api.json listing all components in this package.
-     */
-    apiJsonComponents: ApiCustomElementDeclaration[];
-    /**
-     * Like this.apiJson, but also contains members decorated with the `@private`
-     * JSDoc tag.
-     */
-    privateApiJson: ApiJson;
-    /**
-     * Resolves once api.json is first generated during a given build run.
-     * @private
-     */
-    apiJsonDeferred: PromiseWithResolvers<void> | undefined;
-    /**
-     * In some test environments, api.json will never be produced.
-     */
-    apiJsonEnabled: boolean;
-    /**
-     * Cached result of getLocalDefinedComponentsFromApiJson() call
-     *
-     * @private
-     */
-    _localDefinedComponents?: ReturnType<typeof getLocalDefinedComponentsFromApiJson>;
-    /**
-     * The environment that Vite is running in
-     *
-     * By default, `npx vite` will run in `development` mode. and `npx vite build`
-     * will run in `production` mode. However, you can do a development-mode build
-     * using `npx vite build --mode development`
-     *
-     * - By default, source maps are generated only in development builds.
-     * - Minification happens in production builds.
-     */
-    environment: "development" | "production";
-    /**
-     * It is a best practice to keep local build behavior as similar as possible
-     * to CI build. Thus, only use this option if some behavior really
-     * needs to be different in the CI.
-     *
-     * For example, `@arcgis/lumina-compiler` will by default automatically update
-     * your package's package.json if it is missing some properties. However, this
-     * behavior is disabled on the CI machine.
-     *
-     * @default Boolean(process.env.CI)
-     */
-    readonly isInCi: boolean;
-    /**
-     * It is a best practice to keep production behavior as similar as possible
-     * to test environment. Thus, only use this option if some behavior really
-     * needs to be different in test environment.
-     *
-     * For example, `@arcgis/lumina-compiler` will by default automatically update
-     * your package's package.json if it is missing some properties. However, this
-     * behavior is disabled in test environment.
-     *
-     * Test environment is detected in the following cases:
-     * - Running in test mode (`npx vite build --mode test`). In such case
-     *   CompilerContext.environment will still be set to `development`
-     * - Running in vitest - a test runner for Vite (`npx vitest`)
-     * - Running vitest performance benchmark (`npx vitest benchmark`)
-     */
-    isInTest: boolean;
-    /**
-     * If running inside of Vitest as part of Puppeteer test integration
-     */
-    isInPuppeteerTestBackEnd: boolean;
-    /**
-     * If running in a Vite instance created by Vitest Puppeteer integration.
-     */
-    isInPuppeteerTestFrontEnd: boolean;
-    isInBuildWatch: boolean;
-    /**
-     * Whether Vite build/serve is running inside of Storybook.
-     */
-    isInStorybook: boolean;
-    /**
-     * Whether HMR is enabled during the current Vite run
-     */
-    hmrEnabled: boolean;
-    /**
-     * Vite can be run in two modes:
-     * - Serve the project (with watching for changes and hot module reloading).
-     *   This is the case when you run Vite as `npx vite`
-     * - Build the project (with bundling and optimizations).
-     *   This is the case when you run Vite as `npx vite build`
-     *
-     * `@arcgis/lumina-compiler` does not know what environment Vite is running
-     * in until the `apply()` Vite plugin hook is called by Vite. That means, you
-     * should not try to read this property before the `apply()` hook is called.
-     */
-    viteCommand: ConfigEnv["command"];
-    /**
-     * Whether to extract full API information, with type-checking. This is the
-     * case during build or when running under Storybook. Otherwise, the dev
-     * server keeps API extraction to bare minimum to reduce needless overhead.
-     * Only the information necessary for the dev server to lazy load is
-     * extracted.
-     */
-    isFullApiExtraction: boolean;
-    readonly banner: string;
-    /**
-     * Options passed to `useLumina()`
-     */
-    readonly options: LuminaOptions;
-    /**
-     * Resolved file names for documentation files
-     *
-     * @private
-     */
-    readonly _documentationFileNames: Record<DocsType, string | undefined>;
-    /**
-     * Resolved Vite configuration
-     */
-    viteConfig: ResolvedConfig;
-    /**
-     * Vite's dev server. Set only if Vite is running in serve mode
-     */
-    server: ViteDevServer;
-    /**
-     * Whether configServer() hook has already been called
-     *
-     * @private
-     */
-    _serverConfigured: boolean;
-    /**
-     * Assets pending to be served
-     *
-     * @private
-     */
-    assetsToProvide: ProvideAssetsOptions[] | undefined;
-    /**
-     * A promise that resolves to list of file names that declare one or more
-     * components. This promise only represents the initial scan and is not updated
-     * in watch or serve mode.
-     */
-    componentFilesPromise: Promise<string[]>;
-    /**
-     * Style for hiding custom elements before they are loaded. This is appended
-     * to the global stylesheet.
-     *
-     * @private
-     */
-    _globalHydratedCssString: string;
-    /**
-     * Contents of the bundled global CSS file. The string is JSON-encoded so that
-     * it can be injected into a JavaScript file as a string literal.
-     *
-     * @private
-     */
-    _globalCssString?: string;
-    /**
-     * Cached result of makeLoaders() call
-     *
-     * @private
-     */
-    _loadersCache?: ReturnType<typeof makeLoaders>;
-    /**
-     * Cached result of computeServeOnlyDependencies() call
-     *
-     * @private
-     */
-    _serveOnlyDependencies?: ReturnType<typeof computeServeOnlyDependencies>;
-    /**
-     * Data structure that stores references between class components and between
-     * functional components.
-     * This is used in build mode only.
-     *
-     * @private
-     */
-    _customElementDependencies: CustomElementInterdependencies;
-    /**
-     * Cached result of getPrinter() call. Cached to not needlessly create and
-     * throw away a printer instance for each transformed file.
-     *
-     * @private
-     */
-    _typeScriptPrinter: ReturnType<typeof unsafeGetUndocumentedPrinter>;
-    private _silencedRules;
-    /**
-     * Promise that resolves once src/lumina.ts is updated
-     * @private
-     */
-    _updateLuminaTsPromise?: Promise<void>;
-    /** @private */
-    _originalRollupInputOptions?: Record<string, string> | undefined;
-    constructor(options: LuminaOptions);
-    private _inferBuildSetup;
-    /**
-     * Get TypeScript ts.SourceFile based on file name and code. Reuses existing
-     * source file instance if already created one for that file, and code has not
-     * changed.
-     */
-    getSourceFile(fileName: string, code: string): ts.SourceFile;
-    /**
-     * A utility for making Vite copy assets to the output folder during build or
-     * making Vite serve them when running in serve mode
-     *
-     * @example
-     * ```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],
-     *   };
-     * });
-     * ```
-     */
-    provideAssets(assets: AssetSpec[], transformers?: AssetTransformer[], apply?: CompilerContext["viteCommand"]): void;
-    logLintWarning(error: string): void;
-    logLintError(rule: keyof LintingOptions["silence"], absoluteFilePath: string, error: string): void;
-}
+import type { ConfigEnv } from "vite";
+import type { ApiCustomElementDeclaration, ApiJson } from "@arcgis/api-extractor/apiJson";
+import type { LuminaOptions, AssetSpec, AssetTransformer } from "../options.js";
+import type { ContextDirectories } from "./types.js";
+import type { ApiExtractor } from "@arcgis/api-extractor/extractor/ApiExtractor";
+
+/** A compiler state and context object that is shared across plugins. */
+export abstract class CompilerContext {
+  /**
+   * Core paths selected while exposing ESM modules from Vite's development server.
+   *
+   * @internal
+   */
+  _localCdnCore?: {
+      readonly packageLocation: string;
+      readonly sourceLocation?: string;
+  };
+  apiExtractor?: ApiExtractor;
+  /**
+   * The api.json stores information about the structure of all components in
+   * the package (their properties, methods, events, JSDoc and etc).
+   *
+   * You can augment the api.json generation using the `apiJson` option in
+   * `useLumina()`
+   */
+  apiJson: ApiJson;
+  /** A flattened api.json listing all components in this package. */
+  apiJsonComponents: ApiCustomElementDeclaration[];
+  /** In some test environments, api.json will never be produced. */
+  apiJsonEnabled: boolean;
+  /** List of directories of common interest to the compiler */
+  dir: ContextDirectories;
+  /**
+   * The environment that Vite is running in
+   *
+   * By default, `npx vite` will run in `development` mode. and `npx vite build`
+   * will run in `production` mode. However, you can do a development-mode build
+   * using `npx vite build --mode development`
+   *
+   * - By default, source maps are generated only in development builds.
+   * - Minification happens in production builds.
+   */
+  environment: "development" | "production";
+  /** Whether HMR is enabled during the current Vite run */
+  hmrEnabled: boolean;
+  /**
+   * Whether to extract full API information, with type-checking. This is the
+   * case during build or when running under Storybook. Otherwise, the dev
+   * server keeps API extraction to bare minimum to reduce needless overhead.
+   * Only the information necessary for the dev server to lazy load is
+   * extracted.
+   */
+  isFullApiExtraction: boolean;
+  /** True in `vite build --watch` mode. */
+  isInBuildWatch: boolean;
+  /**
+   * It is a best practice to keep local build behavior as similar as possible
+   * to CI build. Thus, only use this option if some behavior really
+   * needs to be different in the CI.
+   *
+   * For example, `@arcgis/lumina-compiler` will by default automatically update
+   * your package's package.json if it is missing some properties. However, this
+   * behavior is disabled on the CI machine.
+   *
+   * @default Boolean(process.env.CI)
+   */
+  readonly isInCi: boolean;
+  /**
+   * If running inside of Vitest as part of Puppeteer test integration
+   *
+   * @deprecated
+   * For new projects, use Vitest browser mode instead of Puppeteer.
+   * See documentation: https://webgis.esri.com/references/lumina/testing
+   */
+  isInPuppeteerTestBackEnd: boolean;
+  /** If running in a Vite instance created by Vitest Puppeteer integration. */
+  isInPuppeteerTestFrontEnd: boolean;
+  /** Whether Vite build/serve is running inside of Storybook. */
+  isInStorybook: boolean;
+  /**
+   * It is a best practice to keep production behavior as similar as possible
+   * to test environment. Thus, only use this option if some behavior really
+   * needs to be different in test environment.
+   *
+   * For example, `@arcgis/lumina-compiler` will by default automatically update
+   * your package's package.json if it is missing some properties. However, this
+   * behavior is disabled in test environment.
+   *
+   * Test environment is detected in the following cases:
+   * - Running in test mode (`npx vite build --mode test`). In such case
+   *   CompilerContext.environment will still be set to `development`
+   * - Running in vitest - a test runner for Vite (`npx vitest`)
+   * - Running vitest performance benchmark (`npx vitest benchmark`)
+   */
+  isInTest: boolean;
+  /** Options passed to `useLumina()` */
+  readonly options: LuminaOptions;
+  /**
+   * Like this.apiJson, but also contains members decorated with the `@private`
+   * JSDoc tag.
+   */
+  privateApiJson: ApiJson;
+  /**
+   * Whether minification is enabled for transformed JSX (lit-html templates)
+   * and generated component code.
+   *
+   * @internal
+   */
+  shouldMinify: boolean;
+  /**
+   * Like this.shouldMinify, but true when in test mode. Reasons:
+   * - If accessing .textContent, the whitespace amount differs between minified
+   *   and non-minified lit-html templates. In Stencil's JSX this was not the
+   *   case. To ease migration of tests, we minify lit-html in tests too.
+   * - From the above, you can see that minification does change semantics in
+   *   some cases. To have tests be truer to the real world, we minify in tests.
+   *
+   * Also, true during build as per
+   * https://devtopia.esri.com/WebGIS/webgis-sdk/issues/2084
+   *
+   * @internal
+   */
+  shouldMinifyJsx: boolean;
+  /**
+   * Vite can be run in two modes:
+   * - Serve the project (with watching for changes and hot module reloading).
+   *   This is the case when you run Vite as `npx vite`
+   * - Build the project (with bundling and optimizations).
+   *   This is the case when you run Vite as `npx vite build`
+   *
+   * `@arcgis/lumina-compiler` does not know what environment Vite is running
+   * in until the `apply()` Vite plugin hook is called by Vite. That means, you
+   * should not try to read this property before the `apply()` hook is called.
+   */
+  viteCommand: ConfigEnv["command"];
+  /**
+   * A utility for making Vite copy assets to the output folder during build or
+   * making Vite serve them when running in serve mode
+   *
+   * @param assets
+   * @param transformers
+   * @param apply
+   * @example
+   * ```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],
+   *   };
+   * });
+   * ```
+   */
+  provideAssets(assets: AssetSpec[], transformers?: AssetTransformer[], apply?: CompilerContext["viteCommand"]): void;
+}

package/dist/context/types.d.ts

@@ -1,34 +1,18 @@
-export type ContextDirectories = {
-    /**
-     * The project root directory. Usually equals to process.cwd() + '/'
-     */
-    root: string;
-    /**
-     * The source directory. Usually equals dir.root + `src/`
-     */
-    src: string;
-    /**
-     * The components directory. Usually equals dir.src + `components/`
-     */
-    srcComponents: string;
-    /**
-     * The root-relative path to the dist directory. Usually 'dist/'
-     */
-    relativeDist: string;
-    /**
-     * The output directory. Usually equals dir.root + `dist/`
-     */
-    dist: string;
-    /**
-     * The CDN output directory. Usually equals dir.output + `cdn/`
-     */
-    distCdn: string;
-    /**
-     * The components output directory. Usually equals dir.output + `components/`
-     */
-    distComponents: string;
-    /**
-     * The assets output directory. Usually equals dir.output + `cdn/assets/`
-     */
-    distCdnAssets: string;
-};
+export interface ContextDirectories {
+  /** The project root directory. Usually equals to process.cwd() + '/' */
+  root: string;
+  /** The source directory. Usually equals dir.root + `src/` */
+  src: string;
+  /** The components directory. Usually equals dir.src + `components/` */
+  srcComponents: string;
+  /** The root-relative path to the dist directory. Usually 'dist/' */
+  relativeDist: string;
+  /** The output directory. Usually equals dir.root + `dist/` */
+  dist: string;
+  /** The CDN output directory. Usually equals dir.output + `cdn/` */
+  distCdn: string;
+  /** The components output directory. Usually equals dir.output + `components/` */
+  distComponents: string;
+  /** The assets output directory. Usually equals dir.output + `cdn/assets/` */
+  distCdnAssets: string;
+}

package/dist/defaultAssetsUrl.d.ts

@@ -2,14 +2,14 @@
  * Generates a URL like this from the provided package json:
  * `https://js.arcgis.com/<simplified-package-name>/<released-verion>/`
  *
- * @example
- * `https://js.arcgis.com/map-components/4.30/`
- *
- * @remarks
  * If package version number includes "next", `jsdev.arcgis.com` CDN is used
  * instead of `js.arcgis.com`.
+ *
+ * @param packageJson
+ * @param preferNext
+ * @example `https://js.arcgis.com/map-components/4.30/`
  */
-export declare function inferCdnUrl(packageJson?: {
+export function inferCdnUrl(packageJson?: {
     name: string;
     version: string;
-}, preferNext?: boolean): string;
+}, preferNext?: boolean): string;