@lobehub/editor 4.4.0 → 4.6.0

package/es/editor-kernel/lexical/extension-core/types.d.ts

@@ -1,371 +0,0 @@
-/**
- * Copyright (c) Meta Platforms, Inc. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-import type { CreateEditorArgs, EditorState, LexicalEditor } from 'lexical';
-
-import type {
-  LexicalExtensionInternal,
-  configTypeSymbol,
-  initTypeSymbol,
-  outputTypeSymbol,
-  peerDependencySymbol,
-} from './internal';
-
-/**
- * Any concrete {@link LexicalExtension}
- */
-export type AnyLexicalExtension = LexicalExtension<any, string, any, any>;
-/**
- * Any {@link LexicalExtension} or {@link NormalizedLexicalExtensionArgument}
- */
-export type AnyLexicalExtensionArgument =
-  | AnyLexicalExtension
-  | AnyNormalizedLexicalExtensionArgument;
-/**
- * The default extension configuration of an empty object
- */
-export type ExtensionConfigBase = Record<never, never>;
-/**
- * The result of {@link declarePeerDependency}, a tuple of a peer dependency
- * name and its associated configuration.
- */
-export type NormalizedPeerDependency<Extension extends AnyLexicalExtension> = [
-  Extension['name'],
-  Partial<LexicalExtensionConfig<Extension>> | undefined,
-] & {
-  readonly [peerDependencySymbol]?: Extension;
-};
-/**
- * A tuple of `[extension, ...configOverrides]`
- */
-export type NormalizedLexicalExtensionArgument<
-  Config extends ExtensionConfigBase,
-  Name extends string,
-  Output,
-  Init,
-> = [LexicalExtension<Config, Name, Output, Init>, ...Partial<Config>[]];
-/**
- * Any {@link NormalizedLexicalExtensionArgument}
- */
-export type AnyNormalizedLexicalExtensionArgument = NormalizedLexicalExtensionArgument<
-  any,
-  string,
-  any,
-  any
->;
-/**
- * An object that the init method can use to access the
- * configuration for extension dependencies
- */
-export interface ExtensionInitState {
-  /**
-   * Get the result of a peerDependency by name, if it exists
-   * (must be a peerDependency of this extension)
-   */
-  getPeer: <Dependency extends AnyLexicalExtension = never>(
-    name: Dependency['name'],
-  ) => undefined | Omit<LexicalExtensionDependency<Dependency>, 'output' | 'init'>;
-  /**
-   * Get the configuration of a dependency by extension
-   * (must be a direct dependency of this extension)
-   */
-  getDependency: <Dependency extends AnyLexicalExtension>(
-    dep: Dependency,
-  ) => Omit<LexicalExtensionDependency<Dependency>, 'output' | 'init'>;
-  /**
-   * Get the names of any direct dependents of this
-   * Extension, typically only used for error messages.
-   */
-  getDirectDependentNames: () => ReadonlySet<string>;
-  /**
-   * Get the names of all peer dependencies of this
-   * Extension, even if they do not exist in the builder,
-   * typically only used for devtools.
-   */
-  getPeerNameSet: () => ReadonlySet<string>;
-}
-export interface ExtensionBuildState<Init> extends Omit<
-  ExtensionInitState,
-  'getPeer' | 'getDependency'
-> {
-  /**
-   * Get the result of a peerDependency by name, if it exists
-   * (must be a peerDependency of this extension)
-   */
-  getPeer: <Dependency extends AnyLexicalExtension = never>(
-    name: Dependency['name'],
-  ) => undefined | LexicalExtensionDependency<Dependency>;
-  /**
-   * Get the configuration of a dependency by extension
-   * (must be a direct dependency of this extension)
-   */
-  getDependency: <Dependency extends AnyLexicalExtension>(
-    dep: Dependency,
-  ) => LexicalExtensionDependency<Dependency>;
-  /**
-   * The result of the init function
-   */
-  getInitResult: () => Init;
-}
-/**
- * An object that the register method can use to detect unmount and access the
- * configuration for extension dependencies
- */
-export interface ExtensionRegisterState<Init, Output> extends ExtensionBuildState<Init> {
-  /** An AbortSignal that is aborted when this LexicalEditor registration is disposed */
-  getSignal: () => AbortSignal;
-  /**
-   * The result of the output function
-   */
-  getOutput: () => Output;
-}
-/**
- * A {@link LexicalExtension} or {@link NormalizedLexicalExtensionArgument} (extension with config overrides)
- */
-export type LexicalExtensionArgument<
-  Config extends ExtensionConfigBase,
-  Name extends string,
-  Output,
-  Init,
-> =
-  | LexicalExtension<Config, Name, Output, Init>
-  | NormalizedLexicalExtensionArgument<Config, Name, Output, Init>;
-export interface LexicalExtensionDependency<out Dependency extends AnyLexicalExtension> {
-  init: LexicalExtensionInit<Dependency>;
-  config: LexicalExtensionConfig<Dependency>;
-  output: LexicalExtensionOutput<Dependency>;
-}
-/**
- * An Extension is a composable unit of LexicalEditor configuration
- * (nodes, theme, etc) used to create an editor, plus runtime behavior
- * that is registered after the editor is created.
- *
- * An Extension may depend on other Extensions, and provide functionality to other
- * extensions through its config.
- */
-export interface LexicalExtension<
-  Config extends ExtensionConfigBase,
-  Name extends string,
-  Output,
-  Init,
->
-  extends InitialEditorConfig, LexicalExtensionInternal<Config, Output, Init> {
-  /** The name of the Extension, must be unique */
-  readonly name: Name;
-  /**
-   * Extension names that must not be loaded with this Extension.
-   * If this extension and any of the conflicting extensions are configured
-   * in the same editor then a runtime error will be thrown instead of
-   * creating the editor. This is used to prevent extensions with incompatible
-   * and overlapping functionality from being registered concurrently, such as
-   * PlainTextExtension and RichTextExtension.
-   **/
-  conflictsWith?: string[];
-  /** Other Extensions that this Extension depends on, can also be used to configure them */
-  dependencies?: AnyLexicalExtensionArgument[];
-  /**
-   * Other Extensions, by name, that this Extension can optionally depend on or
-   * configure, if they are directly depended on by another Extension
-   */
-  peerDependencies?: NormalizedPeerDependency<AnyLexicalExtension>[];
-  /**
-   * The default configuration specific to this Extension. This Config may be
-   * seen by this Extension, or any Extension that uses it as a dependency.
-   *
-   * The config may be mutated on register, this is particularly useful
-   * for vending functionality to other Extensions that depend on this Extension.
-   */
-  config?: Config;
-  /**
-   * By default, Config is shallow merged `{...a, ...b}` with
-   * {@link shallowMergeConfig}, if your Extension requires other strategies
-   * (such as concatenating an Array) you can implement it here.
-   *
-   * @example
-   * Merging an array
-   * ```js
-   * const extension = defineExtension({
-   *   // ...
-   *   mergeConfig(config, overrides) {
-   *     const merged = shallowMergeConfig(config, overrides);
-   *     if (Array.isArray(overrides.decorators)) {
-   *       merged.decorators = [...config.decorators, ...overrides.decorators];
-   *     }
-   *     return merged;
-   *   }
-   * });
-   * ```
-   *
-   * @param config - The current configuration
-   * @param overrides - The partial configuration to merge
-   * @returns The merged configuration
-   */
-  mergeConfig?: (config: Config, overrides: Partial<Config>) => Config;
-  /**
-   * Perform any necessary initialization before the editor is created,
-   * this runs after all configuration overrides for both the editor this
-   * this extension have been merged. May be used validate the editor
-   * configuration.
-   *
-   * @param editorConfig - The in-progress editor configuration (mutable)
-   * @param config - The merged configuration specific to this extension (mutable)
-   * @param state - An object containing methods for accessing the merged
-   *   configuration of dependencies and peerDependencies
-   */
-  init?: (editorConfig: InitialEditorConfig, config: Config, state: ExtensionInitState) => Init;
-  /**
-   * Perform any tasks that require a LexicalEditor instance, but before
-   * registration has taken place. May provide output to be used by
-   * dependencies or the application (commands, components, etc.).
-   * This will only be run once, and any work performed by the output
-   * function must not require cleanup.
-   */
-  build?: (editor: LexicalEditor, config: Config, state: ExtensionBuildState<Init>) => Output;
-  /**
-   * Add behavior to the editor (register transforms, listeners, etc.) after
-   * the Editor is created, but before its initial state is set.
-   * The register function may also mutate the config
-   * in-place to expose data to other extensions that use it as a dependency.
-   *
-   * @param editor - The editor this Extension is being registered with
-   * @param config - The merged configuration specific to this Extension
-   * @param state - An object containing an AbortSignal that can be
-   *   used, and methods for accessing the merged configuration of
-   *   dependencies and peerDependencies
-   * @returns A clean-up function
-   */
-  register?: (
-    editor: LexicalEditor,
-    config: Config,
-    state: ExtensionRegisterState<Init, Output>,
-  ) => () => void;
-  /**
-   * Run any code that must happen after initialization of the
-   * editor state (which happens after all register calls).
-   *
-   * @param editor - The editor this Extension is being registered with
-   * @param config - The merged configuration specific to this Extension
-   * @param state - An object containing an AbortSignal that can be
-   *   used, and methods for accessing the merged configuration of
-   *   dependencies and peerDependencies
-   * @returns A clean-up function
-   */
-  afterRegistration?: (
-    editor: LexicalEditor,
-    config: Config,
-    state: ExtensionRegisterState<Init, Output>,
-  ) => () => void;
-}
-/**
- * Extract the Config type from an Extension
- */
-export type LexicalExtensionConfig<Extension extends AnyLexicalExtension> = NonNullable<
-  Extension[configTypeSymbol]
->;
-/**
- * Extract the Name type from an Extension
- */
-export type LexicalExtensionName<Extension extends AnyLexicalExtension> = Extension['name'];
-/**
- * Extract the Output type from an Extension
- */
-export type LexicalExtensionOutput<Extension extends AnyLexicalExtension> = NonNullable<
-  Extension[outputTypeSymbol]
->;
-/**
- * Extract the Init type from an Extension
- */
-export type LexicalExtensionInit<Extension extends AnyLexicalExtension> = NonNullable<
-  Extension[initTypeSymbol]
->;
-/**
- * An Extension that has an OutputComponent of the given type (e.g. React.ComponentType)
- */
-export type OutputComponentExtension<ComponentType> = LexicalExtension<
-  any,
-  any,
-  {
-    Component: ComponentType;
-  },
-  any
->;
-/**
- * A handle to the editor with an attached dispose function
- */
-export interface LexicalEditorWithDispose extends LexicalEditor, Disposable {
-  /**
-   * Dispose the editor and perform all clean-up
-   * (also available as Symbol.dispose via Disposable)
-   */
-  dispose: () => void;
-}
-/**
- * All of the possible ways to initialize $initialEditorState:
- * - `null` an empty state, the default
- * - `string` an EditorState serialized to JSON
- * - `EditorState` an EditorState that has been deserialized already (not just parsed JSON)
- * - `((editor: LexicalEditor) => void)` A function that is called with the editor for you to mutate it
- */
-export type InitialEditorStateType =
-  | null
-  | string
-  | EditorState
-  | ((editor: LexicalEditor) => void);
-export interface InitialEditorConfig {
-  /**
-   * @internal Disable root element events (for internal Meta use)
-   */
-  disableEvents?: CreateEditorArgs['disableEvents'];
-  /**
-   * Used when this editor is nested inside of another editor
-   */
-  parentEditor?: CreateEditorArgs['parentEditor'];
-  /**
-   * The namespace of this Editor. If two editors share the same
-   * namespace, JSON will be the clipboard interchange format.
-   * Otherwise HTML will be used.
-   */
-  namespace?: CreateEditorArgs['namespace'];
-  /**
-   * The nodes that this Extension adds to the Editor configuration, will be
-   * merged with other Extensions.
-   *
-   * Can be a function to defer the access of the nodes to editor construction
-   * which may be useful in cases when the node and extension are defined in
-   * different modules and have depenendencies on each other, depending on the
-   * bundler configuration.
-   */
-  nodes?: CreateEditorArgs['nodes'] | (() => CreateEditorArgs['nodes']);
-  /**
-   * EditorThemeClasses that will be deep merged with other Extensions
-   */
-  theme?: CreateEditorArgs['theme'];
-  /**
-   * Overrides for HTML serialization (exportDOM) and
-   * deserialization (importDOM) that does not require subclassing and node
-   * replacement
-   */
-  html?: CreateEditorArgs['html'];
-  /**
-   * Whether the initial state of the editor is editable or not
-   */
-  editable?: CreateEditorArgs['editable'];
-  /**
-   * The editor will catch errors that happen during updates and
-   * reconciliation and call this. It defaults to
-   * `(error) => { throw error }`.
-   *
-   * @param error - The Error object
-   * @param editor - The editor that this error came from
-   */
-  onError?: (error: Error, editor: LexicalEditor) => void;
-  /**
-   * The initial EditorState as a JSON string, an EditorState, or a function
-   * to update the editor (once).
-   */
-  $initialEditorState?: InitialEditorStateType;
-}