@blotch/rsbuild-plugin-angular-lynx 22.2.2 → 22.2.3

package/dist/component-styles-cache.d.ts

@@ -1,20 +1,4 @@
 import type { ComponentStyleSize } from './utils/angular/budgets.js';
-/**
- * Per-component stylesheet bookkeeping. `imports` lists the on-disk scoped CSS
- * paths the loader will prepend as `import` statements; `inlineStyles` mirrors
- * Angular's inline-style handling surface; `processedFiles` deduplicates calls
- * that Angular's AOT compiler makes multiple times for the same stylesheet.
- */
-export type ComponentStylesEntry = {
-    imports: string[];
-    inlineStyles: string[];
-    scopeId: string;
-    processedFiles: Map<string, string>;
-};
-export type ComponentScopeInfo = {
-    className: string;
-    scopeId: string;
-};
 /**
  * Drops the recorded stylesheet sizes of a component whose file was deleted,
  * so `anyComponentStyle` budgets stop reporting styles that no longer ship.
@@ -24,28 +8,14 @@ export declare const forgetComponentStyleSizes: (componentStyleSizes: Map<string
  * Builds the `transformStylesheet` callback that Angular's AOT compiler invokes
  * for every component stylesheet (inline `styles: []` and external `styleUrls`).
  *
- * The callback is a closure over the two shared caches the loader
- * (`api.transform` in angular.ts) later reads from:
- *   - `componentStylesCache` — maps component source file → its scoped CSS imports
- *   - `componentScopeIds` — maps component source file → { className, scopeId }
- *
- * Extracted from angular.ts so the dedup / scoped-path / write-if-changed logic
- * can be unit-tested directly by driving the returned callback, without standing
- * up a full Angular compilation.
+ * It returns the CSS unchanged, so the compiler embeds it in the component's
+ * definition and scopes it for the component's `encapsulation`, as on the web.
+ * extractComponentStyles() (component-styles.ts) then lifts it back out of the
+ * compiled code as Lynx CSS. The callback only records each stylesheet's size,
+ * for `anyComponentStyle` budgets.
  */
 export declare const createTransformStylesheet: (params: {
     basePath: string;
-    scopedCssCacheDir: string;
-    componentStylesCache: Map<string, ComponentStylesEntry>;
-    componentScopeIds: Map<string, ComponentScopeInfo>;
-    /**
-     * Called with the path of each scoped CSS file whose contents were
-     * (re)written. On watch rebuilds the scoped files change after rspack's
-     * watcher has already collected the edit, so angular.ts passes them to
-     * rspack as modified. Otherwise the CSS change would only ship on the
-     * following rebuild.
-     */
-    onStylesheetWritten?: (filePath: string) => void;
     /**
      * The compiled size of every component stylesheet, for `anyComponentStyle`
      * budgets. Overwritten each time Angular compiles a stylesheet, so watch

package/dist/component-styles.d.ts

@@ -0,0 +1,73 @@
+import type { ModuleStylesheets } from './transform-module.js';
+/**
+ * One component's styles, lifted out of its compiled definition.
+ */
+export type ExtractedComponentStyles = {
+    className: string;
+    /**
+     * The ID the runtime builds the scope classes from. Only Emulated components
+     * need one, so it's `undefined` for the others.
+     */
+    scopeId: string | undefined;
+    /** The stylesheets, ready to be written as CSS files. */
+    stylesheets: string[];
+};
+export type ExtractComponentStylesResult = {
+    /** The module's code, without the `styles` the stylesheets came from. */
+    code: string;
+    components: ExtractedComponentStyles[];
+};
+/**
+ * Turns Angular's emulated-encapsulation CSS into CSS that Lynx can match.
+ *
+ * Angular's compiler scopes an Emulated component's styles with attribute
+ * selectors: `.title` becomes `.title[_ngcontent-%COMP%]`, `:host` becomes
+ * `[_nghost-%COMP%]`, and keyframe names gain a `_ngcontent-%COMP%_` prefix. On
+ * the web, the renderer puts those attributes on the elements. Lynx's selector
+ * matcher has no attribute selectors (`SelectorMatcher::MatchSimple` in Lynx
+ * core's css/ng/matcher only handles tag, class, id and pseudo-classes), so the
+ * attributes become classes here, and EmulatedLynxRenderer adds the same
+ * classes to the elements.
+ */
+export declare const toLynxScopedCss: (css: string, scopeId: string) => string;
+/**
+ * Fills the CSS variable namespace placeholder Angular's compiler puts in every
+ * component's styles: `var(--muted)` compiles to `var(--%NS%muted)`. Angular's
+ * renderer fills it with `CSS_VAR_NAMESPACE`, which is empty unless an app
+ * opts in with `provideCssVarNamespacing()`. Lynx CSS is compiled ahead of
+ * time, so it gets the default here, and the variables keep their own names,
+ * which global stylesheets such as the theme define.
+ */
+export declare const fillCssVarNamespace: (css: string) => string;
+/**
+ * Lifts each component's `styles` out of Angular's compiled output, so they
+ * can ship as Lynx CSS.
+ *
+ * Lynx can't add styles at runtime: CSS has to be compiled into the bundle.
+ * So the plugin lets Angular's compiler embed every component's styles in its
+ * definition, exactly as on the web (scoped for `ViewEncapsulation.Emulated`,
+ * left global for `None` and `ShadowDom`), then takes them back out here. That
+ * keeps each component's styles with its own encapsulation, even when two
+ * components share a stylesheet file, and removes the CSS strings from the
+ * JavaScript.
+ *
+ * Only `styles` arrays made of string literals are taken, which is what the
+ * compiler emits. Anything else is left in place.
+ */
+export declare const extractComponentStyles: (code: string, fileName: string) => ExtractComponentStylesResult;
+/**
+ * Writes the stylesheets extracted from one module as CSS files, so the
+ * module can import them and css-extract compiles them into the bundle.
+ *
+ * A file is only rewritten when its content changed, and each rewrite is
+ * reported through `onWritten`: on a watch rebuild the files change after
+ * rspack's watcher collected the edit, so the plugin reports them to rspack as
+ * changed, or the new CSS would only ship on the following rebuild.
+ */
+export declare const writeModuleStylesheets: (params: {
+    basePath: string;
+    cacheDir: string;
+    fileName: string;
+    components: readonly ExtractedComponentStyles[];
+    onWritten?: (filePath: string) => void;
+}) => ModuleStylesheets | undefined;

package/dist/component-styles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cross-thread-transform.d.ts

@@ -0,0 +1,38 @@
+export type CrossThreadTransformOptions = {
+    /** The directory the file keys are relative to, the same for both bundles. */
+    root: string;
+};
+/**
+ * Gives each module-level `backgroundFn(fn)`, `createMainThreadRef(value)` and
+ * `new MainThreadRef(value)` one more argument: an ID from the file and the
+ * call's position, such as `'3f9a1c2b7d:0'`.
+ *
+ * Angular runs on the main thread only, but the background thread runs the
+ * modules that make these calls too (see background-entry.ts), for the
+ * functions that main-thread code calls there. The main thread sends a handle
+ * or ref across by this ID, and the other thread finds its own copy by it.
+ * The runtime's fallback is a counter, which only matches if both threads run
+ * the same calls in the same order. They don't: the background thread runs
+ * only some of the app's modules, and in a different order, and Angular code
+ * (which also creates refs) runs on the main thread only.
+ *
+ * Calls inside a function or class are left alone, since one call site can run
+ * any number of times there.
+ *
+ * @param code - The module's JavaScript.
+ * @param filename - The module's path.
+ * @param options - See {@link CrossThreadTransformOptions}.
+ * @returns The transformed code, or `code` itself when nothing applies.
+ */
+export declare const transformCrossThread: (code: string, filename: string, options: CrossThreadTransformOptions) => string;
+/**
+ * Whether the module calls `backgroundFn()`, `createMainThreadRef()` or
+ * `new MainThreadRef()` at module level, so the background thread has to run
+ * it too. These are the calls {@link transformCrossThread} tags.
+ *
+ * @param code - The module's JavaScript.
+ * @param filename - The module's path.
+ * @returns `true` when the module defines a value the main thread can send
+ *   across by ID.
+ */
+export declare const definesCrossThreadValues: (code: string, filename: string) => boolean;

package/dist/cross-thread-transform.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/css.d.ts

@@ -1,7 +1,7 @@
 import type { RsbuildPluginAPI } from '@lynx-js/rspeedy';
 import type { CSSLoaderOptions } from '@rsbuild/core';
-import type { PluginAngularLynxOptions } from './utils/options.js';
-export declare const applyCSS: (api: RsbuildPluginAPI, options: Required<PluginAngularLynxOptions>) => void;
+import type { NormalizedPluginAngularLynxOptions } from './utils/options.js';
+export declare const applyCSS: (api: RsbuildPluginAPI, options: NormalizedPluginAngularLynxOptions) => void;
 /**
  * This is copied from https://github.com/web-infra-dev/rsbuild/blob/9f8be2d71ffeb7da969cda36fd9755db2cadaff5/packages/core/src/plugins/css.ts#L42
  *

package/dist/entry.d.ts

@@ -1,12 +1,33 @@
 import type { RsbuildPluginAPI, Rspack } from '@lynx-js/rspeedy';
 import type { UndefinedOnPartialDeep } from 'type-fest';
-import type { PluginAngularLynxOptions } from './utils/options.js';
+import type { BackgroundEntries } from './background-entry.js';
+import type { NormalizedPluginAngularLynxOptions } from './utils/options.js';
 /**
  * The key `pluginLynx` (the Lynx build engine, which Rspeedy registers) exposes
  * its resolved config under. Mirrors `S_LYNX_CONFIG` in React Lynx's plugin.
  */
 export declare const S_LYNX_CONFIG: unique symbol;
-export declare const applyEntry: (api: RsbuildPluginAPI, options: Required<PluginAngularLynxOptions>) => void;
+/**
+ * The `blur-view` rule that approximates iOS's blur materials on Android,
+ * from variables the runtime sets (see the file). Only the native bundle gets
+ * it: web draws the materials itself, in the element's shadow root, and an
+ * app-level rule there would beat them. It goes before every other import, so
+ * the app's own stylesheets come later and win a tie.
+ */
+export declare const BLUR_VIEW_STYLESHEET: string;
+/**
+ * The hot update clients (see client/). The background one stands in for
+ * `@rspack/core/hot/dev-server`; the main-thread one gives the main thread its
+ * own hot updates. Together they apply each update on both threads, or reload.
+ */
+export declare const HMR_BACKGROUND_CLIENT: string;
+export declare const HMR_MAIN_THREAD_CLIENT: string;
+/**
+ * Applies stylesheet edits on the main thread, in place of css-extract's
+ * `runtime/hotModuleReplacement.cjs` (see client/css-hot-update.ts).
+ */
+export declare const CSS_HOT_UPDATE: string;
+export declare const applyEntry: (api: RsbuildPluginAPI, options: NormalizedPluginAngularLynxOptions, backgroundEntries: BackgroundEntries, appEntries: Set<string>) => void;
 /**
  * This is copied from https://github.com/web-infra-dev/rsbuild/blob/037da7b9d92e20c7136c8b2efa21eef539fa2f88/packages/core/src/plugins/html.ts#L168
  */

package/dist/hot-updates.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Whether a build environment takes hot updates, under the same conditions
+ * entry.ts adds the hot update clients: a development build of a Lynx
+ * environment (the web preview has none) without `dev.hmr: false`.
+ *
+ * @param environment - The environment, as Rsbuild passes it to a transform.
+ * @returns Whether modules should take hot updates.
+ */
+export declare const hotUpdatesEnabled: (environment: {
+    name: string;
+    config: {
+        mode?: string;
+        dev?: {
+            hmr?: boolean;
+        };
+    };
+}) => boolean;
+/**
+ * Hashes a component file's source without its components' templates and
+ * styles. Two versions of a file with the same signature differ only in what
+ * a hot update can apply in place (see `ɵhmrAccept` in the runtime). An
+ * external template or stylesheet isn't in the source at all, so editing one
+ * leaves the signature as it was.
+ *
+ * @param source - The file's TypeScript source.
+ * @param fileName - The file's path, for the parser.
+ * @returns The signature.
+ */
+export declare const hotUpdateSignature: (source: string, fileName: string) => string;
+/**
+ * Finds the components a module's compiled code defines, as the names of
+ * their classes. Only classes declared at the top of the module are listed,
+ * because the code {@link addHotAccept} appends assigns to them there.
+ *
+ * @param code - The module's code, as Angular's compiler emitted it.
+ * @param fileName - The module's path, for the parser.
+ * @returns The class names, in the order the module defines them.
+ */
+export declare const componentClassNames: (code: string, fileName: string) => string[];
+/**
+ * Makes a module that defines components take its own hot updates, through
+ * the runtime's `ɵhmrAccept`. The call reassigns the module's component
+ * classes to what it returns, so after an in-place update the module's
+ * exports are the classes the running app already uses.
+ *
+ * @param code - The module's code.
+ * @param options.components - The names of the module's component classes.
+ * @param options.signature - The source's {@link hotUpdateSignature}.
+ * @param options.compiled - The code Angular's compiler emitted for the
+ *   module, before the plugin's other transforms.
+ * @returns The code with the call appended.
+ */
+export declare const addHotAccept: (code: string, { components, signature, compiled, }: {
+    components: string[];
+    signature: string;
+    compiled: string;
+}) => string;
+/**
+ * Makes the app's entry module take every hot update its imports pass on.
+ * Re-running the entry calls `bootstrapApplication()` again, which replaces
+ * the running app with one built from the updated modules (on the main
+ * thread; the background thread runs no app).
+ *
+ * @param code - The entry module's code.
+ * @returns The code with the self-accept appended.
+ */
+export declare const addEntryHotAccept: (code: string) => string;

package/dist/hot-updates.test.d.ts

@@ -0,0 +1 @@
+export {};