@arcgis/lumina-compiler 5.2.0-next.8 → 5.2.0-next.9

package/dist/context/index.d.ts

@@ -1,296 +1,158 @@
-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 {
+  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/arcgis-web-components/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;

package/dist/dependencies/discover.d.ts

@@ -1,26 +1,41 @@
-import { PackageJson } from '@arcgis/components-build-utils';
-import { ApiJson } from '@arcgis/api-extractor/apiJson';
-import { LuminaOptions } from '../publicTypes.ts';
-export type ResolvedDependencyComponents = {
-    readonly packageName: string;
-    readonly type: "@arcgis/lumina" | "stencil" | "unknown";
-    readonly components: Readonly<Record<string, ResolvedDependencyComponent>>;
-    readonly cdnUrl?: string;
-    readonly packageLocation: string;
-    readonly packageJson: PackageJson;
-};
-export type ResolvedDependencyComponent = {
-    modulePath: string;
-    packageName: string | undefined;
-    /**
-     * If jsx property has a static value, and we see that an equivalent attribute
-     * exists, jsx property will be converted to an attribute rather than
-     * property. If we failed to read all attributes from a package, it's not a
-     * big deal as we will then play safe and leave jsx properties as properties.
-     */
-    readonly propToAttribute: Readonly<Record<string, string>>;
-    requiredProperties?: Set<string>;
-};
+import type { PackageJson } from "@arcgis/components-build-utils";
+import type { LuminaOptions } from "../options.js";
+
+/** @internal */
+export interface ResolvedDependencyComponents {
+  /** @internal */
+  readonly packageName: string;
+  /** @internal */
+  readonly type: "@arcgis/lumina" | "stencil" | "unknown";
+  /** @internal */
+  readonly components: Readonly<Record<string, ResolvedDependencyComponent>>;
+  /** @internal */
+  readonly cdnUrl?: string;
+  /** @internal */
+  readonly packageLocation: string;
+  /** @internal */
+  readonly packageJson: PackageJson;
+}
+
+/** @internal */
+export interface ResolvedDependencyComponent {
+  /** @internal */
+  readonly modulePath: string;
+  /** @internal */
+  readonly packageName?: string;
+  /**
+   * If jsx property has a static value, and we see that an equivalent attribute
+   * exists, jsx property will be converted to an attribute rather than
+   * property. If we failed to read all attributes from a package, it's not a
+   * big deal as we will then play safe and leave jsx properties as properties.
+   *
+   * @internal
+   */
+  readonly propToAttribute: Readonly<Record<string, string>>;
+  /** @internal */
+  requiredProperties?: ReadonlySet<string>;
+}
+
 /**
  * Read information about our web component dependencies. This will be used to:
  * - know where to auto-import a component from
@@ -49,16 +64,9 @@ export type ResolvedDependencyComponent = {
  *
  * If this does not work for one of your dependencies, provide a custom resolver
  * to autoAddImports() or useLumina().
+ *
+ * @param cwd
+ * @param options
+ * @internal
  */
-export declare function initializeComponentDependencies(cwd?: string, options?: LuminaOptions): Promise<readonly ResolvedDependencyComponents[]>;
-export declare function retrieveComponentDependencies(): readonly ResolvedDependencyComponents[];
-export declare function retrieveFlatComponentDependencies(): ResolvedDependencyComponents["components"];
-export declare let componentDependenciesPromise: Promise<readonly ResolvedDependencyComponents[]> | undefined;
-export declare function findPackageComponents(packageName: string, cwd?: string): Promise<ResolvedDependencyComponents | undefined>;
-/**
- * Given the custom element manifest, find custom elements defined in it
- */
-export declare function manifestToDependencyComponents(manifest: Partial<ApiJson>, dependency: {
-    readonly packageName: string | undefined;
-    readonly getImportPath: (tagName: string) => string;
-}, computeRequiredProperties?: boolean): ResolvedDependencyComponents["components"];
+export function initializeComponentDependencies(cwd?: string, options?: LuminaOptions): Promise<readonly ResolvedDependencyComponents[]>;

package/dist/dependencies/updateLumina.d.ts

@@ -1,11 +1,10 @@
-import { ResolvedDependencyComponents } from './discover.ts';
-export declare function updateLuminaTs(dependencies: readonly ResolvedDependencyComponents[], srcDir: string, 
-/** Preserved positional argument for compatibility because codemod was passing it */
-_unused?: never, 
-/** Preserved positional argument for compatibility because codemod was passing it */
-_unused2?: never, packageJson?: import('@arcgis/components-build-utils').PackageJson): Promise<boolean>;
-declare function produceLuminaTs(dependencies: readonly ResolvedDependencyComponents[], packageJson?: import('@arcgis/components-build-utils').PackageJson): string;
-export declare const exportsForTests: {
-    produceLuminaTs: typeof produceLuminaTs;
-};
-export {};
+import type { PackageJson } from "@arcgis/components-build-utils";
+import type { ResolvedDependencyComponents } from "./discover.js";
+
+/**
+ * @param dependencies
+ * @param srcDir
+ * @param packageJson
+ * @internal
+ */
+export function updateLuminaTs(dependencies: readonly ResolvedDependencyComponents[], srcDir: string, packageJson?: PackageJson): Promise<boolean>;