@arcgis/lumina-compiler 4.33.0-next.98 → 4.33.0

package/dist/jsxToLitHtml/config.d.ts

@@ -36,7 +36,7 @@ export declare const nativeAlwaysAttributes: Set<string>;
  * These don't exist as a property, only as an attribute.
  * Or, the property is read-only, but the attribute is not.
  */
-export declare const htmlAlwaysAttributes: Record<string, Set<string>>;
+export declare const htmlAlwaysAttributes: Record<string, Set<string> | undefined>;
 /**
  * The mappings between native DOM property and the equivalent attribute it
  * reflects to.

package/dist/jsxToLitHtml/imports.d.ts

@@ -1,6 +1,5 @@
 import { default as ts } from 'typescript';
 import { JsxContext } from './types';
-export declare const dynamicallyInsertedImportPaths: Set<string>;
 /**
  * This runs before we know what imports will be needed.
  *

package/dist/logger-KpGU2b3R.js

@@ -0,0 +1,28 @@
+import { toSystemPathSeparators as i, path as c } from "@arcgis/components-build-utils";
+import a from "chalk";
+import { createLogger as g } from "vite";
+let n = g(), s = process.cwd();
+function e(r, o, t) {
+  return typeof t == "string" ? (t = t.startsWith(s) ? i(c.relative(s, t)) : t, t = `${t}: `) : t = "", `${r} ${t}${o}`;
+}
+const f = {
+  initialize(r, o) {
+    n = r, s = o;
+  },
+  info(r, o, t) {
+    n.info(e(a.cyan(`[${r}]`), o, t));
+  },
+  warn(r, o, t) {
+    n.warn(e(a.yellow(`[${r}]`), o, t));
+  },
+  error(r, o, t) {
+    n.error(e(a.red(`[${r}]`), o, t)), process.exitCode = 1;
+  }
+};
+function u(r, o, t) {
+  return o instanceof Error ? (o.message = e(r, o.message, t), o) : e(a.red(`[${r}]`), o, t);
+}
+export {
+  u as f,
+  f as l
+};

package/dist/plugins/buildCdn.d.ts

@@ -1,21 +1,24 @@
 import { Plugin } from 'vite';
 import { CompilerContext } from '../context';
+import { CdnChunk } from '../publicTypes';
 /**
  * Restricted due to collisions with Lumina's dist/ folder names or
  * Stencil's dist/ folder names
  */
 export declare const restrictedNamespaceNames: Set<string>;
 export declare const defaultNamespace = "cdn";
+export declare const defaultEntryJsName = "index";
+export declare const globalCssName = "main";
 /**
  * CDN build works by reading the lazy NPM build and bundling-in all used
  * dependencies (except for imports of web components from dependencies - those
  * are assumed to be defined in the environment separately)
  */
 export declare function buildCdn(context: CompilerContext): Plugin | undefined;
-type Chunk = {
-    code: string;
-    isAsync: boolean | undefined;
-};
+export declare function buildLoaderCode(runtimeVariableName: string, customEntrypoints: {
+    in: string;
+    out: string;
+}[]): string;
 /**
  * Transform each core-importing chunk to use $arcgis.t for loading core in
  * order to be both ESM and AMD CDN compatible.
@@ -27,9 +30,9 @@ type Chunk = {
  * and https://bugs.webkit.org/show_bug.cgi?id=242740), we are no longer using
  * top-level await.
  *
- * Instead, we insert a top-level await polyfill - a promise called $$ is
- * exported by core-containing modules - such promise needs to be awaited by the
- * consuming modules before the imported variables are available.
+ * Instead, we insert a top-level await polyfill - any module that imports core
+ * directly or indirectly is transformed to have a promise as a default export -
+ * such promise, once awaited, yields the actual exports of the module.
  *
  * List of other solutions considered:
  * https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/3999
@@ -45,43 +48,24 @@ type Chunk = {
  * export { s as ArcgisNavigationToggle };
  *
  * /// AFTER
- * // $$ is a promise we need to await before imports from that module are available
- * import { $$ as _0, b } from "./U7MU7PMX.js";
- * var _1,
- *   $$ = $arcgis.t(
- *     ([{ when: M }]) => {
- *       // The "meat" of the file is kept unchanged by the transform
- *       // (we only touch the imports, and the very last export line)
- *         s = class extends v {
- *           // ...
- *         };
- *       // Assign exported variables to global scope variables
- *       _1 = s;
- *     },
- *     "core/reactiveUtils",
- *     _0,
- *   );
- * // _1 will only be assigned once $$ resolves
- * export { $$, _1 as ArcgisNavigationToggle };
- * ```
- */
-declare function transformChunk(chunk: Chunk, chunks: Map<string, Chunk>): void;
-/**
- * @example Dynamic core import
- * ```diff
- * - import("core/Handles");
- * + $arcgis.t(_=>_[0],"core/Handles")
- * ```
- *
- * @example Dynamic import of a chunk with top-level await
- * ```diff
- * - import("./chunk.js");
- * + import("./chunk.js").then(m=>m.$$.then(_=>m))
+ * import a from "./U7MU7PMX.js";
+ * export default $arcgis.t(
+ *   ([{ when: M }, { b }]) => {
+ *     // The "meat" of the file is kept unchanged by the transform
+ *     // (we only touch the imports, and the very last export line)
+ *       s = class extends v {
+ *         // ...
+ *       };
+ *     // Resolve the promise by returning the exported class
+ *     return s;
+ *   },
+ *   "core/reactiveUtils",
+ *   a,
+ * );
  * ```
  */
-declare function transformDynamicCoreImports(code: string, chunks: Map<string, Chunk>): string;
+declare function transformChunk(chunk: CdnChunk, chunks: Map<string, CdnChunk>): void;
 export declare const exportsForTests: {
-    transformDynamicCoreImports: typeof transformDynamicCoreImports;
     transformChunk: typeof transformChunk;
 };
 export {};

package/dist/plugins/configureVite.d.ts

@@ -1,9 +1,9 @@
 import { Plugin } from 'vite';
 import { CompilerContext } from '../context';
-import { PuppeteerLaunchOptions } from 'puppeteer';
 import { InlineConfig } from 'vitest/node';
+import { PuppeteerTestingOptions } from '../publicTypes';
 export type PuppeteerVitestConfigOptions = InlineConfig & {
-    puppeteerLaunchOptions?: PuppeteerLaunchOptions;
+    puppeteerLaunchOptions?: PuppeteerTestingOptions["launchOptions"];
     puppeteerWaitForChangesDelay?: number;
 };
 /**

package/dist/plugins/updatePackageJson.d.ts

@@ -2,7 +2,7 @@ import { MiniPackageJson } from '@arcgis/components-build-utils';
 import { CompilerContext } from '../context';
 import { Plugin } from 'vite';
 export declare const updatePackageJson: (context: CompilerContext) => Plugin;
-declare function doPackageJsonUpdate(packageJson: MiniPackageJson, context: Pick<CompilerContext, "_documentationFileNames" | "dir">): MiniPackageJson | undefined;
+declare function doPackageJsonUpdate(packageJson: MiniPackageJson, context: Pick<CompilerContext, "_documentationFileNames" | "dir" | "options">): MiniPackageJson | undefined;
 export declare const exportsForTests: {
     doPackageJsonUpdate: typeof doPackageJsonUpdate;
 };

package/dist/publicTypes.d.ts

@@ -4,10 +4,9 @@ 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 { PuppeteerLaunchOptions } from 'puppeteer';
 import { WebTypesOptions } from './docs/webTypes/types';
 import { VsCodeDocOptions } from './docs/vsCodeCustomData/types';
-import { ApiJson, ApiModule } from '@arcgis/api-extractor';
+import { ApiJson, ApiModule, CopyDocDefinitions } from '@arcgis/api-extractor';
 import { LuminaApiExtractor } from './extractor/extractor';
 /**
  * `useLumina()` returns an array of Vite plugins. The array additionally
@@ -71,6 +70,7 @@ export type BuildOptions = {
      * Configuration for CDN build.
      */
     readonly cdn?: BuildCdnOptions;
+    /** @deprecated Use Storybook build or separate test app package. */
     readonly webApp?: {
         /**
          * If set, will produce a web app build, based on index.html files and
@@ -127,19 +127,39 @@ export type BuildCdnOptions = {
      */
     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 lazy-loading build of your
-     * package, and post-processes it with ESBuild. You can customize the options
-     * passed to ESBuild.
+     * 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];
+    /**
+     * A callback for mutating CDN 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.
+     */
+    readonly transformer?: (chunks: Map<string, CdnChunk>, context: CompilerContext) => void;
+};
+export type CdnChunk = {
+    code: string;
+    isAsync: boolean | undefined;
+    oldSingleExportName: string | undefined;
 };
 /**
  * Generic type for the different kinds of wrappers.
@@ -231,6 +251,24 @@ export type DependencyManagementOptions = Omit<RollupPluginNodeExternalsOptions,
      * technical reasons.
      */
     readonly externalize?: NonNullable<RollupPluginNodeExternalsOptions>["include"];
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * // Silence errors for unknown custom elements that start with "fluent-"
+     * silenceUnknownJsxElementUsage: (tagName) => tagName.startsWith("fluent-")
+     * ```
+     */
+    readonly silenceUnknownJsxElementUsage?: (tagName: string, fileName: string, context: CompilerContext) => boolean;
 };
 export type ServeEnvironmentOptions = {
     /**
@@ -270,9 +308,20 @@ export type PuppeteerTestingOptions = {
      * @default 0
      */
     readonly waitForChangesDelay?: number;
-    readonly launchOptions?: PuppeteerLaunchOptions;
+    /**
+     * @example
+     * ```ts
+     * import type { LaunchOptions } from "puppeteer";
+     * // ...
+     *   launchOptions: {
+     *     args: ["--no-sandbox", "--disable-setuid-sandbox"],
+     *   } satisfies LaunchOptions;
+     * ```
+     */
+    readonly launchOptions?: Record<string, unknown>;
 };
 export type GenerateDocumentationOptions = {
+    readonly copyDefinitions?: CopyDocDefinitions;
     /**
      * The name of the file to write the api.json to. api.json is a file format
      * based on custom-elements-manifest that describes all the components in the
@@ -285,22 +334,39 @@ export type GenerateDocumentationOptions = {
      * 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;
+    /**
+     * Get a prefix for a public-facing URL for each component story.
+     *
+     * @example
+     * Set this to "https://developers.arcgis.com/javascript/latest/storybook/map-components/".
+     * This will produce URLs like
+     * "https://developers.arcgis.com/javascript/latest/storybook/map-components/?path=/story/arcgis-area-measurement-2d--demo&singleStory=true"
+     * @see https://qawebgis.esri.com/components/lumina/storybook
+     */
+    readonly publicStoryUrlPrefix?: string;
     /**
      * Provide a URL to a page that documents the component.
      * This URL will be visible in VS Code and IntelliJ when hovering over a
      * component tag in an .html file
+     *
+     * @example (tagName) => `https://developers.arcgis.com/javascript/latest/references/map-components/${tagName}/`
      */
-    readonly getComponentDocsUrl?: (tag: string, name: string) => string | undefined;
+    readonly getComponentDocsUrl?: (tagName: string, className: string) => string | undefined;
     /**
      * Provide a URL to a page that documents the component.
      * This URL will be visible in VS Code and IntelliJ when hovering over a
      * component tag in an .html file
+     *
+     * If you wish to provide multiple URLs, use "getPublicStoryUrl" instead.
+     *
+     * @example (tagName) => `https://developers.arcgis.com/javascript/latest/storybook/map-components/?path=/story/${tagName}--demo&singleStory=true`
      */
-    readonly getComponentDemoUrl?: (tag: string, name: string) => string | undefined;
+    readonly 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.
@@ -346,7 +412,7 @@ export type GenerateTypesOptions = Omit<VitePluginDtsOptions, "beforeWriteFile"
      * This transformer is used only on .d.ts files of your components. Any
      * .d.ts files for utility files or other non-entrypoint files are not
      * affected by this transformer. For those, you can use the
-     * `declarationAstTransformers` option.
+     * `declarationTextTransformers` option.
      */
     readonly declarationAstTransformers?: FileTransformer[];
     /**
@@ -425,7 +491,7 @@ export type ApiJsonOptions = {
      *
      * @default LuminaApiExtractor
      */
-    readonly Extractor: typeof LuminaApiExtractor;
+    readonly Extractor?: typeof LuminaApiExtractor;
     /**
      * This function will be called after the api.json is created but before it is
      * used to generate any output files.
@@ -663,14 +729,14 @@ export type AssetTransformer = {
 };
 export type LintingOptions = {
     /**
-     * Lumina emits build-time errors for common issues and possible bugs.
+     * 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 temporary turn these errors into warnings.
+     * This option exists to temporarily turn these errors into warnings.
      * @example
-     * To silence an error in a file, add an entry like thw following with the
+     * To silence an error in a file, add an entry like the following with the
      * relative path to the file:
      *
      * ```ts
@@ -678,13 +744,6 @@ export type LintingOptions = {
      * ```
      */
     silence: {
-        /**
-         * Default values for boolean properties must default to false (or
-         * undefined), never to true.
-         *
-         * [Documentation](https://qawebgis.esri.com/components/lumina/properties#boolean-properties)
-         */
-        booleanMustDefaultFalse?: string[];
         /**
          * Lumina components may declare required properties using `@required` JSDoc
          * tag.