// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

/**
 * {@inheritDoc CompatVisitorConfig.addComponentElement}
 * @public
 */
export 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;
}

export interface DarkModeConfig {
  /**
   * @public
   * Theme expression to be used for dark mode
   */
  themeExpr: string;
}

/**
 * {@inheritDoc CompatVisitorConfig.addComponentElement}
 * @public
 */

/**
 * {@inheritDoc PluginReactLynxOptions.compat}
 * @public
 */
export interface CompatVisitorConfig {
  /** @internal */
  target: 'LEPUS' | 'JS' | 'MIXED';
  /**
   * @public
   * Specifies the list of component package names that need compatibility processing
   *
   * @defaultValue `['@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
   *
   * @defaultValue `['@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
   *
   * @defaultValue `'@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.
   *
   * @defaultValue `[]`
   *
   * @remarks
   * This only takes effect when {@link CompatVisitorConfig.addComponentElement} is enabled.
   *
   * @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
   *
   * @defaultValue `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
   *
   * @defaultValue `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
   * Whether to transform legacy event attribute names on Lynx elements.
   *
   * When enabled, legacy event attributes such as `onClick` and
   * `onClickCatch` are transformed to `bindtap` and `catchtap`.
   * Disable this when another transform owns event attribute-name conversion.
   *
   * @defaultValue `true`
   */
  transformLegacyEventAttributeNames?: 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.
   *
   * @defaultValue `undefined`
   *
   * @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
   *
   * @defaultValue `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
   *
   * @defaultValue `undefined`
   *
   * @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;
}