@arcgis/lumina-compiler 4.34.0-next.90 → 4.34.0-next.96

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/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:
  *

package/dist/publicTypes.d.ts

@@ -507,59 +507,6 @@ 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 = {
     /**

package/dist/transformers/injectRuntimeOptions.d.ts

@@ -1,3 +1,13 @@
 import { CompilerContext } from '../context';
 import { TransformResult } from 'vite';
 export declare function injectRuntimeOptions(runtimeTsCode: string, context: CompilerContext): TransformResult;
+/**
+ * Add to chunks/runtime.js import statement for the global CSS file.
+ * This way CSS is injected automatically, simplifying get started instructions.
+ * We also inject CSS imports for Lumina dependencies this package uses - this
+ * is needed to ensure CSS is loaded in correct order - this does not cause
+ * duplicate CSS bundling.
+ *
+ * Research notes: https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/1824#discussioncomment-12625
+ */
+export declare function getGlobalCssImport(context: CompilerContext): string;

package/dist/transformers/utils.d.ts

@@ -6,9 +6,3 @@ import { CompilerContext } from '../context';
  * the resulting source file
  */
 export declare function runTransformers(context: CompilerContext, transformationContext: ts.TransformationContext, sourceFile: ts.SourceFile, transformers: readonly FileTransformer[]): ts.SourceFile;
-/**
- * For performance reasons, to avoid the need to re-create the source map
- * after this change, replace the given code string with a comment string of
- * equal length :)
- */
-export declare const commentOutCode: (match: string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/lumina-compiler",
-  "version": "4.34.0-next.90",
+  "version": "4.34.0-next.96",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -18,9 +18,9 @@
   ],
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@arcgis/api-extractor": "4.34.0-next.90",
-    "@arcgis/components-build-utils": "4.34.0-next.90",
-    "@arcgis/toolkit": "4.34.0-next.90",
+    "@arcgis/api-extractor": "4.34.0-next.96",
+    "@arcgis/components-build-utils": "4.34.0-next.96",
+    "@arcgis/toolkit": "4.34.0-next.96",
     "chalk": "^5.4.1",
     "esbuild": "^0.25.5",
     "glob": "^11.0.3",
@@ -31,7 +31,7 @@
     "vitest-fail-on-console": "^0.7.1"
   },
   "peerDependencies": {
-    "@arcgis/lumina": "~4.34.0-next.90",
+    "@arcgis/lumina": "~4.34.0-next.96",
     "lit": "^3.3.0",
     "typescript": "~5.8.3",
     "vite": "^7.0.0",