@lynx-js/react-rsbuild-plugin 0.9.10 → 0.10.1

package/dist/index.d.ts

@@ -1,8 +1,766 @@
-/**
- * @packageDocumentation
- *
- * A rsbuild plugin that integrates with ReactLynx.
- */
-export { pluginReactLynx } from './pluginReactLynx.js';
-export type { PluginReactLynxOptions } from './pluginReactLynx.js';
-export { LAYERS } from '@lynx-js/react-webpack-plugin';
+/**
+ * @packageDocumentation
+ *
+ * A rsbuild plugin that integrates with ReactLynx.
+ */
+
+import { LAYERS } from '@lynx-js/react-webpack-plugin';
+import type { RsbuildPlugin } from '@rsbuild/core';
+
+/**
+ * {@inheritdoc CompatVisitorConfig.addComponentElement}
+ * @public
+ */
+export declare interface AddComponentElementConfig {
+    /**
+     * @public
+     * Whether to only add component element during compilation
+     *
+     * @example
+     *
+     * Note that this only take effects on `Component` imported from {@link CompatVisitorConfig.oldRuntimePkg}.
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         addComponentElement: { compilerOnly: true }
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    compilerOnly: boolean
+}
+
+/**
+ * {@inheritdoc PluginReactLynxOptions.compat}
+ * @public
+ */
+export declare interface CompatVisitorConfig {
+    /** @internal */
+    target: 'LEPUS' | 'JS' | 'MIXED'
+    /**
+     * @public
+     * Specifies the list of component package names that need compatibility processing
+     *
+     * @remarks
+     * Default value: `['@lynx-js/react-components']`
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         componentsPkg: ['@my-org/components', '@legacy/ui-kit']
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    componentsPkg: Array<string>
+    /**
+     * @public
+     * Specifies the list of old runtime package names that need compatibility processing
+     *
+     * @remarks
+     * Default value: `['@lynx-js/react-runtime']`
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         oldRuntimePkg: ['@my-org/runtime', '@legacy/runtime']
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    oldRuntimePkg: Array<string>
+    /**
+     * @public
+     * Specifies the new runtime package name
+     *
+     * @remarks
+     * Default value: `'@lynx-js/react'`
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         newRuntimePkg: '@my-org/react'
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    newRuntimePkg: string
+    /**
+     * @public
+     * Specifies additional component attributes list, these attributes will be passed to the wrapped `<view>` instead of the component.
+     *
+     * @remarks
+     * This only takes effect when {@link CompatVisitorConfig.addComponentElement} is enabled.
+     *
+     * Default value: `[]`
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         additionalComponentAttributes: ['custom-attr', 'data-special']
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    additionalComponentAttributes: Array<string>
+    /**
+     * @public
+     * Controls whether to add wrapper elements for components
+     *
+     * @remarks
+     * Default value: `false`
+     *
+     * @example
+     *
+     * Add a `<view>` wrapper element for all components during runtime.
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         addComponentElement: true
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     *
+     * @example
+     *
+     * Only add component element during compilation.
+     * Note that this only take effects on `Component` imported from {@link CompatVisitorConfig.oldRuntimePkg}.
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         addComponentElement: { compilerOnly: true }
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    addComponentElement: boolean | AddComponentElementConfig
+    /**
+     * @public
+     * Whether to simplify constructor calls like ReactLynx 2
+     *
+     * @deprecated
+     * Using `simplifyCtorLikeReactLynx2` is not recommended as it introduces implicit behaviors that can:
+     *
+     * - Make code harder to understand and maintain
+     *
+     * - Create hidden dependencies between components
+     *
+     * - Complicate debugging and testing processes
+     *
+     * Instead, use `background-only` on class methods for explicit and maintainable behavior
+     *
+     * @remarks
+     * Default value: `false`
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         simplifyCtorLikeReactLynx2: true
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    simplifyCtorLikeReactLynx2: boolean
+    /**
+     * @public
+     * Regular expression used to remove component attributes
+     *
+     * @deprecated It's recommended to use `background-only`.
+     *
+     * If your code depends on this switch, when distributing it to other projects through npm packages or other means, you'll also need to enable this switch. This will lead to the proliferation of switches, which is not conducive to code reuse between different projects.
+     *
+     * @remarks
+     * Default value: `None`
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         removeComponentAttrRegex: '^data-test-'
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    removeComponentAttrRegex?: string
+    /**
+     * @public
+     * Whether to disable deprecated warnings
+     *
+     * @remarks
+     * Default value: `false`
+     *
+     * @example
+     *
+     * Disable all the `DEPRECATED:` warnings.
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         disableDeprecatedWarning: true
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    disableDeprecatedWarning: boolean
+    /**
+     * @public
+     * @deprecated
+     * Dark mode configuration
+     *
+     * @remarks
+     * Default value: `None`
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       compat: {
+     *         darkMode: true
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    darkMode?: boolean | DarkModeConfig
+}
+
+declare interface DarkModeConfig {
+    /**
+     * @public
+     * Theme expression to be used for dark mode
+     */
+    themeExpr: string
+}
+
+/**
+ * {@inheritdoc PluginReactLynxOptions.defineDCE}
+ * @public
+ */
+export declare interface DefineDceVisitorConfig {
+    /**
+     * @public
+     * Replaces variables in your code with other values or expressions at compile time.
+     *
+     * @remarks
+     * Caveat: differences between `source.define`
+     *
+     * `defineDCE` happens before transforming `background-only` directives.
+     * So it's useful for eliminating code that is only used in the background from main-thread.
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       defineDCE: {
+     *         define: {
+     *           __FOO__: 'false',
+     *           'process.env.PLATFORM': '"lynx"',
+     *         },
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     *
+     * Then, `__FOO__` and `process.env.PLATFORM` could be used in source code.
+     *
+     * ```
+     * if (process.env.PLATFORM === 'lynx') {
+     *   console.log('lynx')
+     * }
+     *
+     * function FooOrBar() {
+     *   if (__FOO__) {
+     *     return <text>foo</text>
+     *   } else {
+     *     return <text>bar</text>
+     *   }
+     * }
+     * ```
+     */
+    define: Record<string, string>
+}
+
+/**
+ * {@inheritdoc PluginReactLynxOptions.extractStr}
+ * @public
+ */
+export declare interface ExtractStrConfig {
+    /**
+     * @public
+     * The minimum length of string literals to be extracted.
+     *
+     * @remarks
+     * Default value: `20`.
+     *
+     * @example
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       extractStr: {
+     *         strLength: 10,
+     *       },
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    strLength: number
+    /** @internal */
+    extractedStrArr?: Array<string>
+}
+
+export { LAYERS }
+
+/**
+ * Create a rsbuild plugin for ReactLynx.
+ *
+ * @example
+ * ```ts
+ * // rsbuild.config.ts
+ * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+ * export default {
+ *   plugins: [pluginReactLynx()]
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function pluginReactLynx(userOptions?: PluginReactLynxOptions): RsbuildPlugin;
+
+/**
+ * Options of {@link pluginReactLynx}
+ *
+ * @public
+ */
+export declare interface PluginReactLynxOptions {
+    /**
+     * The `compat` option controls compatibilities with ReactLynx2.0.
+     *
+     * @remarks
+     *
+     * These options should only be used for migrating from ReactLynx2.0.
+     */
+    compat?: Partial<CompatVisitorConfig> & {
+        /**
+         * Whether disable runtime warnings about using ReactLynx2.0-incompatible `SelectorQuery` APIs.
+         *
+         * @example
+         * Using the following APIs will have a runtime warning by default:
+         *
+         * ```ts
+         * this.createSelectorQuery()
+         * this.getElementById()
+         * this.getNodeRef()
+         * this.getNodeRefFromRoot()
+         * ```
+         *
+         * @defaultValue `false`
+         */
+        disableCreateSelectorQueryIncompatibleWarning?: boolean;
+    } | undefined;
+    /**
+     * When {@link PluginReactLynxOptions.enableCSSInheritance} is enabled, `customCSSInheritanceList` can control which properties are inheritable, not just the default ones.
+     *
+     * @example
+     *
+     * By setting `customCSSInheritanceList: ['direction', 'overflow']`, only the `direction` and `overflow` properties are inheritable.
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *  plugins: [
+     *    pluginReactLynx({
+     *      enableCSSInheritance: true,
+     *      customCSSInheritanceList: ['direction', 'overflow']
+     *    }),
+     *  ],
+     * }
+     * ```
+     */
+    customCSSInheritanceList?: string[] | undefined;
+    /**
+     * debugInfoOutside controls whether the debug info is placed outside the template.
+     *
+     * @remarks
+     * This is recommended to be set to true to reduce template size.
+     *
+     * @public
+     */
+    debugInfoOutside?: boolean;
+    /**
+     * defaultDisplayLinear controls whether the default value of `display` in CSS is `linear`.
+     *
+     * @remarks
+     *
+     * If `defaultDisplayLinear === false`, the default `display` would be `flex` instead of `linear`.
+     */
+    defaultDisplayLinear?: boolean;
+    /**
+     * enableAccessibilityElement set the default value of `accessibility-element` for all `<view />` elements.
+     */
+    enableAccessibilityElement?: boolean;
+    /**
+     * enableICU enables the Intl API to be enabled globally.
+     *
+     * If enabled, please double check the compatibility with Lynx Share Context feature to avoid using shared Intl API from other destroyed card.
+     *
+     * @defaultValue `false`
+     */
+    enableICU?: boolean;
+    /**
+     * enableCSSInheritance enables the default inheritance properties.
+     *
+     * @remarks
+     *
+     * The following properties are inherited by default:
+     *
+     * - `direction`
+     *
+     * - `color`
+     *
+     * - `font-family`
+     *
+     * - `font-size`
+     *
+     * - `font-style`
+     *
+     * - `font-weight`
+     *
+     * - `letter-spacing`
+     *
+     * - `line-height`
+     *
+     * - `line-spacing`
+     *
+     * - `text-align`
+     *
+     * - `text-decoration`
+     *
+     * - `text-shadow`
+     *
+     * It is recommended to use with {@link PluginReactLynxOptions.customCSSInheritanceList} to avoid performance issues.
+     */
+    enableCSSInheritance?: boolean;
+    /**
+     * CSS Invalidation refers to the process of determining which elements need to have their styles recalculated when the DOM is updated.
+     *
+     * @example
+     *
+     * If a descendant selector `.a .b` is defined in a CSS file, then when an element's class changes to `.a`, all nodes in its subtree with the className `.b` need to have their styles recalculated.
+     *
+     * @remarks
+     *
+     * When using combinator to determine the styles of various elements (including descendants, adjacent siblings, etc.), it is recommended to enable this feature. Otherwise, only the initial class setting can match the corresponding combinator, and subsequent updates will not recalculate the related styles.
+     *
+     * We find that collecting invalidation nodes and updating them is a relatively time-consuming process.
+     * If there is no such usage and better style matching performance is needed, this feature can be selectively disabled.
+     */
+    enableCSSInvalidation?: boolean;
+    /**
+     * enableCSSSelector controls whether enabling the new CSS implementation.
+     *
+     * @public
+     */
+    enableCSSSelector?: boolean;
+    /**
+     * enableNewGesture enables the new gesture system.
+     *
+     * @defaultValue `false`
+     */
+    enableNewGesture?: boolean;
+    /**
+     * enableParallelElement enables Threaded Element Resolution.
+     *
+     * @defaultValue `true`
+     *
+     * @public
+     */
+    enableParallelElement?: boolean;
+    /**
+     * enableRemoveCSSScope controls whether CSS is restrict to use in the component scope.
+     *
+     * `true`: All CSS files are treated as global CSS.
+     *
+     * `false`: All CSS files are treated as scoped CSS, and only take effect in the component that explicitly imports it.
+     *
+     * `undefined`: Only use scoped CSS for CSS Modules, and treat other CSS files as global CSS. Scoped CSS is faster than global CSS, thus you can use CSS Modules to speedy up your CSS if there are performance issues.
+     *
+     * @defaultValue `true`
+     *
+     * @public
+     */
+    enableRemoveCSSScope?: boolean | undefined;
+    /**
+     * This flag controls when MainThread (Lepus) transfers control to Background after the first screen
+     *
+     * This flag has two options:
+     *
+     * `"immediately"`: Transfer immediately
+     *
+     * `"jsReady"`: Transfer when background (JS Runtime) is ready
+     *
+     * After handing over control, MainThread (Lepus) runtime can no longer respond to data updates,
+     * and data updates will be forwarded to background (JS Runtime) and processed __asynchronously__
+     *
+     * @defaultValue "immediately"
+     */
+    firstScreenSyncTiming?: 'immediately' | 'jsReady';
+    /**
+     * `enableSSR` enable Lynx SSR feature for this build.
+     *
+     * @defaultValue `false`
+     *
+     * @public
+     */
+    enableSSR?: boolean;
+    /**
+     * Composite configuration representing pipeline scheduling strategies, including {@link PluginReactLynxOptions.enableParallelElement} and list batch-rendering. All newly introduced scheduling strategies will be managed by this uint64 configuration.
+     *
+     * @remarks
+     *
+     * Preallocate 64 bit unsigned integer for pipeline scheduler config.
+     *
+     * -  0 ~ 7 bit: Reserved for parsing binary bundle into C++ bundle.
+     *
+     * -  8 ~ 15 bit: Reserved for MTS Render.
+     *
+     * -  16 ~ 23 bit: Reserved for resolve stage in Pixel Pipeline.
+     *
+     * -  24 ~ 31 bit: Reserved for layout stage in Pixel Pipeline.
+     *
+     * -  32 ~ 39 bit: Reserved for execute UI OP stage in Pixel Pipeline.
+     *
+     * -  40 ~ 47 bit: Reserved for paint stage in Pixel Pipeline.
+     *
+     * -  48 ~ 63 bit: Flexible bits for extensibility.
+     *
+     * @defaultValue `0x00010000`
+     */
+    pipelineSchedulerConfig?: number;
+    /**
+     * removeDescendantSelectorScope is used to remove the scope of descendant selectors.
+     */
+    removeDescendantSelectorScope?: boolean;
+    /**
+     * How main-thread code will be shaken.
+     */
+    shake?: Partial<ShakeVisitorConfig> | undefined;
+    /**
+     * Like `define` in various bundlers, but this one happens at transform time, and a DCE pass will be performed.
+     */
+    defineDCE?: Partial<DefineDceVisitorConfig> | undefined;
+    /**
+     * `engineVersion` specifies the minimum Lynx Engine version required for an App bundle to function properly.
+     *
+     * @public
+     */
+    engineVersion?: string;
+    /**
+     * targetSdkVersion is used to specify the minimal Lynx Engine version that a App bundle can run on.
+     *
+     * @public
+     * @deprecated `targetSdkVersion` is now an alias of {@link PluginReactLynxOptions.engineVersion}. Use {@link PluginReactLynxOptions.engineVersion} instead.
+     */
+    targetSdkVersion?: string;
+    /**
+     * Merge same string literals in JS and Lepus to reduce output bundle size.
+     * Set to `false` to disable.
+     *
+     * @defaultValue false
+     */
+    extractStr?: Partial<ExtractStrConfig> | boolean;
+    /**
+     * Generate standalone lazy bundle.
+     *
+     * @alpha
+     */
+    experimental_isLazyBundle?: boolean;
+}
+
+/**
+ * {@inheritdoc PluginReactLynxOptions.shake}
+ * @public
+ */
+export declare interface ShakeVisitorConfig {
+    /**
+     * Package names to identify runtime imports that need to be processed
+     *
+     * @example
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       shake: {
+     *         pkgName: ['@lynx-js/react-runtime']
+     *       }
+     *     })
+     *   ]
+     * })
+     * ```
+     *
+     * @remarks
+     * Default value: `['@lynx-js/react-runtime']`
+     * The provided values will be merged with the default values instead of replacing them.
+     * @public
+     */
+    pkgName: Array<string>
+    /**
+     * Properties that should be retained in the component class
+     *
+     * @example
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       shake: {
+     *         retainProp: ['myCustomMethod']
+     *       }
+     *     })
+     *   ]
+     * })
+     * ```
+     *
+     * @remarks
+     * Default value: `['constructor', 'render', 'getDerivedStateFromProps', 'state', 'defaultDataProcessor', 'dataProcessors', 'contextType', 'defaultProps']`
+     * The provided values will be merged with the default values instead of replacing them.
+     *
+     * @public
+     */
+    retainProp: Array<string>
+    /**
+     * Function names whose parameters should be removed during transformation
+     *
+     * @example
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
+     *
+     * export default defineConfig({
+     *   plugins: [
+     *     pluginReactLynx({
+     *       shake: {
+     *         removeCallParams: ['useMyCustomEffect']
+     *       }
+     *     })
+     *   ]
+     * })
+     * ```
+     *
+     * @remarks
+     * Default value: `['useEffect', 'useLayoutEffect', '__runInJS', 'useLynxGlobalEventListener', 'useImperativeHandle']`
+     * The provided values will be merged with the default values instead of replacing them.
+     *
+     * @public
+     */
+    removeCallParams: Array<string>
+}
+
+export { }