@arcgis/lumina-compiler 4.34.0-next.13 → 4.34.0-next.131

package/dist/jsxToLitHtml/importsConfig.d.ts

@@ -0,0 +1,10 @@
+import { JsxImportName } from './types';
+/**
+ * Most Lit API's are re-exported from multiple packages. Because only Lit
+ * package is declared as an explicit dependency, Lumina's auto-inserted imports
+ * should only import from the Lit package (from the first import path in the
+ * lists below). However, to avoid double-importing things if the file already
+ * imports these APIs from another package, we need to check for all the places
+ * that export these APIs (the 2nd+ items in the lists below).
+ */
+export declare const dynamicallyInsertedImportsByName: Record<JsxImportName, string[]>;

package/dist/jsxToLitHtml/types.d.ts

@@ -63,10 +63,12 @@ export declare const ambiguousSvgTag: unique symbol;
 export declare const cssTag = "css";
 export declare const mathMlTag = "mathml";
 declare const litTagsArray: readonly ["css", "html", "mathml", "staticHtml", "staticSvg", "svg"];
-export declare const litTags: Set<"html" | "css" | "mathml" | "staticHtml" | "staticSvg" | "svg">;
+export declare const litTags: Set<"html" | "svg" | "css" | "mathml" | "staticHtml" | "staticSvg">;
 export type LitTag = (typeof litTagsArray)[number];
-export declare const jsxImportNames: readonly ["keyed", "ref", "repeat", "live", "css", "html", "mathml", "staticHtml", "staticSvg", "svg", "safeClassMap", "safeStyleMap", "deferLoad", "nothing"];
+export declare const jsxImportNames: readonly ["keyed", "ref", "repeat", "live", "css", "html", "mathml", "staticHtml", "staticSvg", "svg", "safeClassMap", "safeStyleMap", "deferLoad", "stabilizedRef", "nothing"];
 export type JsxImportName = (typeof jsxImportNames)[number];
 export type JsxHost = ts.JsxElement | ts.JsxFragment | ts.JsxSelfClosingElement;
+/** Returns `true` if the given node is an array expression containing jsx nodes */
+export declare const isJsxArray: (node: ts.Node) => node is ts.ArrayLiteralExpression;
 export declare const isJsxHost: (node: ts.Node) => node is JsxHost;
 export {};

package/dist/loader/{hideUntilHydrated.d.ts → css.d.ts}

@@ -9,7 +9,12 @@ export declare const defaultHydratedAttribute = "hydrated";
  * @see https://discord.com/channels/1012791295170859069/1274527043614150708
  */
 export declare function getGlobalCssInjectionCode(globalCssString: string | undefined, context: CompilerContext): string;
-/**
+/**a
  * Get a CSS string that can be printed into a .css file
+ *
+ * Global CSS is auto-imported by bundlers. To ensure it is always loaded with
+ * lower precedence order than user styles, we wrap it in `@layer{}`.
+ *
+ * @see https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/1824#discussioncomment-12625
  */
 export declare const getGlobalCssAsString: (context: CompilerContext) => string;

package/dist/logger-hJvg0JOj.js

@@ -0,0 +1,34 @@
+import { setApiExtractorErrorLogger as c } from "@arcgis/api-extractor";
+import { toSystemPathSeparators as i, path as g } from "@arcgis/components-build-utils";
+import a from "chalk";
+let e = {
+  // Temporary logger to use until vite config is loaded and we have access to
+  // actual logger.
+  info: console.log,
+  warn: console.warn,
+  error: console.error
+}, s = process.cwd();
+function n(t, r, o) {
+  return typeof o == "string" ? (o = o.startsWith(s) ? i(g.relative(s, o)) : o, o = `${o}: `) : o = "", `${t} ${o}${r}`;
+}
+const f = {
+  initialize(t, r) {
+    e = t, s = r, c(e.error);
+  },
+  info(t, r, o) {
+    e.info(n(a.cyan(`[${t}]`), r, o));
+  },
+  warn(t, r, o) {
+    e.warn(n(a.yellow(`[${t}]`), r, o));
+  },
+  error(t, r, o) {
+    e.error(n(a.red(`[${t}]`), r, o)), process.exitCode = 1;
+  }
+};
+function l(t, r, o) {
+  return r instanceof Error ? (r.message = n(t, r.message, o), r) : n(a.red(`[${t}]`), r, o);
+}
+export {
+  l as f,
+  f as l
+};

package/dist/plugins/buildCdn.d.ts

@@ -65,7 +65,13 @@ export declare function buildLoaderCode(runtimeVariableName: string, customEntry
  * ```
  */
 declare function transformChunk(chunk: CdnChunk, chunks: Map<string, CdnChunk>): void;
+/**
+ * Given set of identifiers, produce the shortest possible ASCII-only identifier.
+ * We restrict to ASCII-range as it is faster to parse for engines.
+ */
+declare function createIdentifierGenerator(seen: Set<string>): () => string;
 export declare const exportsForTests: {
     transformChunk: typeof transformChunk;
+    createIdentifierGenerator: typeof createIdentifierGenerator;
 };
 export {};

package/dist/plugins/loadLitCss.d.ts

@@ -1,6 +1,22 @@
 import { Plugin } from 'vite';
 import { CompilerContext } from '../context';
+/**
+ * CSS extension list taken from https://github.com/vitejs/vite/blob/a8c7083a3d7d7fe2e83e994ff008f39ee4f298f8/packages/vite/src/node/constants.ts#L50
+ */
 export declare const cssLangsRe: RegExp;
+/**
+ * A flag added by Lumina at compile time to named CSS imports to turn
+ * them into Lit css`` tagged template literals (using `styles` named import).
+ *
+ * We do not automatically process every CSS file to allow for both:
+ * - keeping side-effect CSS imports inside external library code as is
+ *   - tricky to do using resolveId() because ESBuild is used for some files in
+ *     dev server.
+ * - explicitly importing external library's CSS as Lit css into shadow root
+ *   - example: monaco or ckeditor styles, but attached into shadow root, rather
+ *     than global
+ */
+export declare const litCssFlag = "?litCss";
 /**
  * The `.adoptedStyleSheets` API is very convenient, but it has one issue: it
  * has higher precedence order than the `<link>` or `<style>` tags. This API was
@@ -12,18 +28,42 @@ export declare const cssLangsRe: RegExp;
  * More information:
  * https://discord.com/channels/1012791295170859069/1274527043614150708
  */
-export declare const layeredCssFlag = "?layered";
+export declare const layeredLitCssFlag = "?layeredLitCss";
 /**
- * During build, we insert a side-effect import into the loader.ts file purely
- * so that the transform() is triggered for that file so that we can piggy back
- * on the transformed output (and create a separate .css file out of it). We do
- * not intend for such file to be included in the JS bundle in the NPM build.
- * Such import will be dropped by the minifier.
- *
- * It's a bit hacky, but that is needed to workaround this Vite behavior:
- * https://github.com/vitejs/vite/pull/11469#:~:text=Further%2C%20this.load%20is%20supposed%20to%20trigger%20transform%20and%20moduleParsed%20%2D%20this%20does%20not%20(in%20accordance%20with%20vite%27s%20on%2Ddemand%20nature
+ * Vite's library mode has CSS support (https://vite.dev/guide/build.html#css-support).
+ * However, if global css file references assets, the library mode will insert
+ * the assets base path in the CSS file. This does not work for us since the
+ * asset path is determined at runtime - provided by the user.
+ *
+ * Additionally, Vite's library mode css handling does not quite fit our use case:
+ * - We need to transform the global CSS to add hydrate CSS
+ *   - Trickier given that we need to emit hydrate CSS even if user did not
+ *     provide global css
+ * - Vite has css chunking support, which we don't need
+ * - We need to add an import for our CSS file (and those of libraries we are
+ *   consuming) in runtime.ts, without processing the external CSS files
+ *
+ * It is possible to make Vite's library mode css work, but requires too much
+ * effort. Instead, we are bypassing Vite's global CSS handling and doing the
+ * simple handling sufficient for our single global css file:
+ * - During build, we insert a import into the loader.ts file purely
+ *   so that the transform() is triggered for that file so that we can piggy back
+ *   on the transformed output (and create a separate .css file out of it).
+ *   Such import has no side-effects and is removed by Rollup.
+ *
+ *   This is the only way to trigger the CSS transform without getting it added
+ *   to the bundle because of this Vite behavior:
+ *   https://github.com/vitejs/vite/pull/11469#:~:text=Further%2C%20this.load%20is%20supposed%20to%20trigger%20transform%20and%20moduleParsed%20%2D%20this%20does%20not%20(in%20accordance%20with%20vite%27s%20on%2Ddemand%20nature
+ * - We manually write dist/main.css based on hydrate CSS and global CSS.
+ * - During generateBundle() stage, we transform the emitted chunks/runtime.js
+ *   to add the import to global CSS for our library and web component libraries
+ *   we are consuming. We do this in generateBundle() stage so that such imports
+ *   are not processed by bundler. Additionally, our loadLitCss plugin's
+ *   transform() has a detection of side-effect CSS imports to error for them
+ *   saying they should be import as named to be added to the shadow root - by
+ *   doing this in generateBundle(), we bypass that check.
  */
-export declare const globalCssFlag = "?global";
+export declare const globalCssFileFlag = "?globalFileLitCss";
 /**
  * Given a CSS file like:
  *
@@ -56,7 +96,7 @@ export declare const globalCssFlag = "?global";
  *
  * Then, we augment it into this:
  * ```js
- * import { css } from '@lit/reactive-element/css-tag.js';
+ * import { css } from 'lit/css-tag.js';
  * const styles = css`:host{display:flex;gap:1rem}button{padding:1rem}`;
  * export default styles;
  * ```
@@ -84,3 +124,4 @@ export declare const globalCssFlag = "?global";
  * will be inlined as base64 to simplify our life.
  */
 export declare const loadLitCss: (context: CompilerContext) => Plugin;
+export declare function viteCssModuleToLit(code: string, withHmr: boolean, minify: boolean, isLayered: boolean): string;

package/dist/publicTypes.d.ts

@@ -3,9 +3,9 @@ import { Plugin } from 'vite';
 import { build as esbuildBuild } from 'esbuild';
 import { CompilerContext } from './context';
 import { PluginOptions as VitePluginDtsOptions } from 'vite-plugin-dts';
-import { ExternalsOptions as RollupPluginNodeExternalsOptions } from 'rollup-plugin-node-externals';
 import { WebTypesOptions } from './docs/webTypes/types';
 import { VsCodeDocOptions } from './docs/vsCodeCustomData/types';
+import { DependencyManagementOptions as BaseDependencyManagementOptions } from '@arcgis/components-build-utils';
 import { ApiJson, ApiModule, CopyDocDefinitions } from '@arcgis/api-extractor';
 import { LuminaApiExtractor } from './extractor/extractor';
 /**
@@ -64,6 +64,10 @@ export type LuminaOptions = {
      */
     readonly assets?: AssetHandlingOptions;
     readonly linting?: LintingOptions;
+    readonly experimental?: {
+        /** @deprecated See https://discord.com/channels/1012791295170859069/1047015641225371718 */
+        readonly stabilizeRef?: boolean;
+    };
 };
 export type BuildOptions = {
     /**
@@ -79,9 +83,13 @@ export type BuildOptions = {
          * @default undefined
          * @example "www"
          * @see [Based on Stencil's www build](https://stenciljs.com/docs/www)
-         * @deprecated Use Storybook build or separate test app package.
+         * @deprecated Use Storybook build or a separate test app package.
          */
         readonly destination?: string;
+        /** @deprecated Use Storybook build or a separate test app package. */
+        readonly transformFile?: (htmlContent: string, htmlFilePath: string, context: CompilerContext) => string;
+        /** @deprecated Use Storybook build or a separate test app package. */
+        readonly afterBuildEnd?: (context: CompilerContext) => Promise<void> | void;
     };
     /**
      * Options for externalizing or bundling in dependencies.
@@ -92,7 +100,7 @@ export type BuildOptions = {
      * New lines are accepted.
      * Do not include // or /* - will be added automatically.
      *
-     * @default require("@arcgis/components-utils").getPreamble()
+     * @default require("@arcgis/toolkit/string").getPreamble()
      *
      * @example
      * ```js
@@ -113,7 +121,6 @@ export type BuildOptions = {
      * Wrappers to generate.
      */
     readonly wrappers?: WrappersOptions[];
-    readonly ssr?: SsrOptions;
 };
 export type BuildCdnOptions = {
     /**
@@ -149,7 +156,15 @@ export type BuildCdnOptions = {
      */
     readonly esbuildOptions?: Parameters<typeof esbuildBuild>[0];
     /**
-     * A callback for mutating CDN chunks before they are written to disk.
+     * 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.
+     */
+    readonly 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.
@@ -158,6 +173,11 @@ export type BuildCdnOptions = {
 };
 export type CdnChunk = {
     code: string;
+    /**
+     * Whether chunk is currently being processed. Used to detect cyclical imports.
+     * @private
+     */
+    isProcessing: boolean;
     isAsync: boolean | undefined;
     oldSingleExportName: string | undefined;
 };
@@ -168,32 +188,6 @@ export type CdnChunk = {
  * 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.
  *
@@ -211,46 +205,31 @@ export type React18WrapperOptions = {
 /**
  * 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"> & {
+export type DependencyManagementOptions = BaseDependencyManagementOptions & {
     /**
-     * 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:
+     * 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.
      *
-     * - 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.
+     * > [!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.
      *
      * @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.
+     * ```ts
+     * // Silence errors for unknown custom elements that start with "fluent-"
+     * silenceUnknownJsxElementUsage: (tagName) => tagName.startsWith("fluent-")
+     * ```
      */
-    readonly externalize?: NonNullable<RollupPluginNodeExternalsOptions>["include"];
+    readonly silenceUnknownJsxElementUsage?: (tagName: string, fileName: string, context: CompilerContext) => boolean;
 };
 export type ServeEnvironmentOptions = {
     /**
@@ -274,7 +253,11 @@ export type ServeEnvironmentOptions = {
 export type DetailedExtraDependency = {
     /** @example "@arcgis/map-config-components" */
     name: string;
-    /** @example ():string => `https://example.com/arcgis-components/builds/main/cdn/map-config-components/` */
+    /**
+     * Overwrite the default CDN asset path for this dependency.
+     *
+     * @example (): string => `https://example.com/arcgis-components/builds/main/cdn/map-config-components/`
+     */
     getCdnUrl: (context: CompilerContext) => string;
 };
 export type PuppeteerTestingOptions = {
@@ -537,65 +520,27 @@ export type CssHandlingOptions = {
      * @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
      *
+     * @example
+     * ```ts
+     * import resolvePkg from "resolve-pkg";
+     *
+     * // ...
+     *
+     * extra: [
+     *   {
+     *     type: "directory",
+     *     source: resolvePkg("@arcgis/arcade-sdk/dist/arcgis-arcade-editor")!,
+     *     destination: "arcade-language",
+     *   },
+     * ]
+     * ```
+     *
      * @remarks
      * If you need additional flexibility, you can call the
      * `compilerContext.provideAssets()` utility at any time

package/dist/puppeteerTesting/index.js

@@ -1,7 +1,7 @@
 import { expect as p, afterEach as V } from "vitest";
 import { toSystemPathSeparators as L, isPosix as S } from "@arcgis/components-build-utils";
 import { p as T, i as h } from "../types-C3YmWTVv.js";
-import { l as y } from "../logger-KpGU2b3R.js";
+import { l as y } from "../logger-hJvg0JOj.js";
 async function D(s) {
   await s.exposeFunction("puppeteerOnEvent", (e, t) => {
     j(s._e2eEvents, e, t);

package/dist/puppeteerTesting/vitest/matchers/index.d.ts

@@ -1,17 +1,17 @@
 export declare const expectExtend: {
-    toEqualAttribute: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toEqualAttributes: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toEqualText: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveAttribute: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveClass: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
+    toEqualAttribute: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toEqualAttributes: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toEqualText: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveAttribute: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveClass: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
     toHaveClasses: (element: unknown, expectClassNames: string[]) => import('@vitest/expect').SyncExpectationResult;
-    toMatchClasses: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveReceivedEvent: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveReceivedEventTimes: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveFirstReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveLastReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
-    toHaveNthReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState>;
+    toMatchClasses: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveReceivedEvent: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveReceivedEventTimes: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveFirstReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveLastReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
+    toHaveNthReceivedEventDetail: import('@vitest/expect').RawMatcherFn<import('@vitest/expect').MatcherState, any[]>;
 };
 export interface PuppeteerMatchers<R = unknown> {
     toEqualAttribute: (expectedAttribute: string, expectedValue: unknown) => R;

package/dist/testing/failOnConsole.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Based on https://github.com/thomasbrodusch/vitest-fail-on-console/, but
+ * simplified and with our fixes applied:
+ * https://github.com/thomasbrodusch/vitest-fail-on-console/issues/61
+ */
+export declare function failOnConsole(): void;