@arcgis/lumina-compiler 4.33.0-next.16 → 4.33.0-next.160

package/dist/publicTypes.d.ts

@@ -1,14 +1,13 @@
-import type ts from "typescript";
-import type { Plugin } from "vite";
-import type { build as esbuildBuild } from "esbuild";
-import type { CompilerContext } from "./context";
-import type { PluginOptions as VitePluginDtsOptions } from "vite-plugin-dts";
-import type { ExternalsOptions as RollupPluginNodeExternalsOptions } from "rollup-plugin-node-externals";
-import type { PuppeteerLaunchOptions } from "puppeteer";
-import type { WebTypesOptions } from "./docs/webTypes/types";
-import type { VsCodeDocOptions } from "./docs/vsCodeCustomData/types";
-import type { ApiJson, ApiModule } from "@arcgis/api-extractor";
-import type { LuminaApiExtractor } from "./extractor/extractor";
+import { default as ts } from 'typescript';
+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 { ApiJson, ApiModule, CopyDocDefinitions } from '@arcgis/api-extractor';
+import { LuminaApiExtractor } from './extractor/extractor';
 /**
  * `useLumina()` returns an array of Vite plugins. The array additionally
  * has a `context` property for accessing the compiler context.
@@ -71,6 +70,19 @@ 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
+         * cdn build.
+         *
+         * @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.
+         */
+        readonly destination?: string;
+    };
     /**
      * Options for externalizing or bundling in dependencies.
      */
@@ -115,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.
@@ -219,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 = {
     /**
@@ -237,7 +287,13 @@ export type ServeEnvironmentOptions = {
      * `index.html`.
      * In such case, you can set `extraDependencies: ["@arcgis/map-components"]`
      */
-    readonly extraDependencies?: string[];
+    readonly extraDependencies?: (DetailedExtraDependency | string)[];
+};
+export type DetailedExtraDependency = {
+    /** @example "@arcgis/map-config-components" */
+    name: string;
+    /** @example ():string => `https://example.com/arcgis-components/builds/main/cdn/map-config-components/` */
+    getCdnUrl: (context: CompilerContext) => string;
 };
 export type PuppeteerTestingOptions = {
     /**
@@ -252,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
@@ -267,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.
@@ -328,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[];
     /**
@@ -407,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.
@@ -645,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
@@ -660,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.

package/dist/puppeteerTesting/globalSetup.d.ts

@@ -1,5 +1,5 @@
-import type { GlobalSetupContext } from "vitest/dist/node.js";
-import { type ConnectOptions } from "puppeteer";
+import { GlobalSetupContext } from 'vitest/dist/node.js';
+import { ConnectOptions } from 'puppeteer';
 declare module "vitest" {
     interface ProvidedContext {
         isDevToolsEnabled?: boolean;

package/dist/puppeteerTesting/globalSetup.js

@@ -1,4 +1,95 @@
-import"../chunk-JFKSI6I7.js";import{launch as l}from"puppeteer";import{createServer as a}from"vite";async function m(t){process.cwd()!==t.config.root&&process.chdir(t.config.root);let[r,e]=await Promise.all([p(t),d(t)]);return async()=>{await Promise.all([e.close(),r.close()]),setInterval(()=>{e.watcher.close()},100).unref()}}async function p(t){let r=t.config,e=r.puppeteerLaunchOptions??{},o=1e3*60*60,s={acceptInsecureCerts:!0,protocolTimeout:e.devtools?o:void 0,args:["--force-prefers-no-reduced-motion",...e.args??[]],...e,headless:e.headless??(e.devtools?void 0:"shell")},n=await l(s),i={...s,browserWSEndpoint:n.wsEndpoint()};return t.provide("puppeteerConnectOptions",i),t.provide("isDevToolsEnabled",s.devtools??!1),t.provide("isHeadlessBrowser",e.headless===void 0?e.devtools!==!0:e.headless!==!1),t.provide("puppeteerWaitForChangesDelay",r.puppeteerWaitForChangesDelay),n}async function d(t){let r={__IS_IN_PUPPETEER__:!0},e=await a({logLevel:"error",server:{open:!1,hmr:!1},root:t.config.root,mode:t.config.mode,clearScreen:!1,define:r});return await e.listen(),await v(t,e),c(t,e),e}async function v(t,r){let e=await r.transformIndexHtml("/",`<!doctype html>
+import { launch as i } from "puppeteer";
+import { createServer as l } from "vite";
+async function h(r) {
+  process.cwd() !== r.config.root && process.chdir(r.config.root);
+  const [o, e] = await Promise.all([c(r), d(r)]);
+  return async () => {
+    await Promise.all([e.close(), o.close()]), setInterval(() => {
+      e.watcher.close();
+    }, 100).unref();
+  };
+}
+async function c(r) {
+  const o = r.config, e = o.puppeteerLaunchOptions ?? {}, t = 1e3 * 60 * 60, s = {
+    acceptInsecureCerts: !0,
+    /**
+     * Allow stopping on a "debugger;" breakpoint for 30 min. Default was 3min.
+     */
+    protocolTimeout: e.devtools ? t : void 0,
+    /**
+     * Force animations to be enabled to run tests consistently regardless of OS
+     * settings.
+     */
+    args: ["--force-prefers-no-reduced-motion", ...e.args ?? []],
+    ...e,
+    /**
+     * The "new" headless mode is running very slow when you have multiple
+     * browser tabs open (running tests concurrently). The slowdown seems to be
+     * most prominent around `requestAnimationFrame()`, which sometimes takes
+     * up to 15s! It indeed appears that `requestAnimationFrame()` is one tab
+     * is blocked until several other tabs complete and close.
+     *
+     * All these issues are fixed by using the old headless mode. It is marked
+     * to be removed from Puppeteer in 2024. However, we are looking to migrate
+     * away from Puppeteer toward Vitest Browser Mode (Playwright) anyway.
+     *
+     * See:
+     * - https://github.com/puppeteer/puppeteer/issues/11944#issuecomment-1967860373
+     * - https://github.com/puppeteer/puppeteer/issues/10109
+     * - https://github.com/puppeteer/puppeteer/issues/12982
+     */
+    headless: e.headless ?? (e.devtools ? void 0 : "shell")
+  }, n = await i(s), a = { ...s, browserWSEndpoint: n.wsEndpoint() };
+  return r.provide("puppeteerConnectOptions", a), r.provide("isDevToolsEnabled", s.devtools ?? !1), r.provide(
+    "isHeadlessBrowser",
+    /**
+     * Default value for headless depends on devtools argument:
+     * https://github.com/puppeteer/puppeteer/blob/b5f08d55401dcfbcfd5d885920ec5098f96ab249/packages/puppeteer-core/src/node/ChromeLauncher.ts#L241-L242
+     */
+    e.headless === void 0 ? e.devtools !== !0 : e.headless !== !1
+  ), r.provide("puppeteerWaitForChangesDelay", o.puppeteerWaitForChangesDelay), n;
+}
+async function d(r) {
+  const o = {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    __IS_IN_PUPPETEER__: !0
+  }, e = await l({
+    /**
+     * Do not clutter tests console with Vite logs.
+     * Also, this matches the setting that Vitest uses when it starts up Vite.
+     */
+    logLevel: "error",
+    server: {
+      /**
+       * Vitest should not auto-open the page (as it would do so in the default
+       * browser). Instead, if you want to see the page, you should start
+       * puppeteer in headed mode, which will open the browser for you.
+       */
+      open: !1,
+      /**
+       * On code changes, browser page reloading will cause a Puppeteer page
+       * navigation, which will fail the test. Instead of HMR, use Vitest
+       * watch mode.
+       */
+      hmr: !1
+    },
+    /**
+     * This should be process.cwd() in most cases, but setting in here just in
+     * case
+     */
+    root: r.config.root,
+    // Set mode to "test"
+    mode: r.config.mode,
+    // This interferes with the Vitest output
+    clearScreen: !1,
+    define: o
+  });
+  return await e.listen(), await v(r, e), p(r, e), e;
+}
+async function v(r, o) {
+  const e = await o.transformIndexHtml(
+    "/",
+    `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
@@ -8,4 +99,16 @@ import"../chunk-JFKSI6I7.js";import{launch as l}from"puppeteer";import{createSer
 </head>
 <body>
 </body>
-</html>`);t.provide("devServerHtml",e)}function c(t,r){let e=r.resolvedUrls,o=e?.local.at(0)??e?.network.at(0);if(o===void 0)throw new Error("Failed to resolve the dev server URL");t.provide("devServerUrl",o)}export{m as setup};
+</html>`
+  );
+  r.provide("devServerHtml", e);
+}
+function p(r, o) {
+  const e = o.resolvedUrls, t = e?.local.at(0) ?? e?.network.at(0);
+  if (t === void 0)
+    throw new Error("Failed to resolve the dev server URL");
+  r.provide("devServerUrl", t);
+}
+export {
+  h as setup
+};

package/dist/puppeteerTesting/index.d.ts

@@ -1,11 +1,10 @@
-import "vitest";
-import type { PuppeteerMatchers } from "./vitest/matchers";
-export type * from "./puppeteer/types";
-export type { NewE2EPageOptions } from "./puppeteer/page";
-export { newE2EPage } from "./puppeteer/page";
-export type { E2EElement } from "./puppeteer/element";
-export type { EventSpy } from "./puppeteer/events";
-export { setupPuppeteerTest } from "./vitest/setupFile";
+import { PuppeteerMatchers } from './vitest/matchers';
+export type * from './puppeteer/types';
+export type { NewE2EPageOptions } from './puppeteer/page';
+export { newE2EPage } from './puppeteer/page';
+export type { E2EElement } from './puppeteer/element';
+export type { EventSpy } from './puppeteer/events';
+export { setupPuppeteerTest } from './vitest/setupFile';
 declare module "vitest" {
     interface Assertion<T = any> extends PuppeteerMatchers<T> {
     }