@examind/block-types 0.1.25 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@examind/block-types",
-  "version": "0.1.25",
+  "version": "0.1.28",
   "@comment version": [
     "Don't specify package version here. It will be injected by publish workflow."
   ],

package/types/examind/nodes/JournalEntryQuestionNode.ts

@@ -4,11 +4,7 @@ import {
   type Spread,
 } from '../../lexical';
 
-const JournalTypes = [
-  'default',
-  'noEntryRequiredCorrect',
-  'noEntryRequiredDistractor',
-] as const;
+const JournalTypes = ['default', 'noEntryRequiredCorrect'] as const;
 
 export type JournalType = (typeof JournalTypes)[number];
 
@@ -23,7 +19,7 @@ export type SerializedJournalEntryQuestionItem = {
 export type SerializedJournalEntryQuestionNode = Spread<
   {
     id: string;
-    journalType: JournalType;
+    noEntryRequired: boolean;
     points: number;
     errorTolerance?: number;
     lineItems: Array<SerializedJournalEntryQuestionItem>;

package/types/lexical/LexicalConstants.ts

@@ -49,3 +49,4 @@ export declare const ELEMENT_FORMAT_TO_TYPE: Record<number, ElementFormatType>;
 export declare const TEXT_MODE_TO_TYPE: Record<TextModeType, 0 | 1 | 2>;
 export declare const TEXT_TYPE_TO_MODE: Record<number, TextModeType>;
 export declare const NODE_STATE_KEY = "$";
+export declare const PROTOTYPE_CONFIG_METHOD = "$config";

package/types/lexical/LexicalEditor.ts

@@ -7,6 +7,7 @@
 import type { EditorState, SerializedEditorState } from './LexicalEditorState';
 import type { DOMConversion, DOMConversionMap, DOMExportOutput, DOMExportOutputMap, NodeKey } from './LexicalNode';
 import { LexicalNode } from './LexicalNode';
+import { SharedNodeState } from './LexicalNodeState';
 import { UpdateTag } from './LexicalUpdateTags';
 export type Spread<T1, T2> = Omit<T2, keyof T1> & T1;
 export type KlassConstructor<Cls extends GenericConstructor<any>> = GenericConstructor<InstanceType<Cls>> & {
@@ -32,9 +33,25 @@ export type TextNodeThemeClasses = {
     [key: string]: EditorThemeClassName | undefined;
 };
 export type EditorUpdateOptions = {
+    /**
+     * A function to run once the update is complete. See also {@link $onUpdate}.
+     */
     onUpdate?: () => void;
+    /**
+     * Setting this to true will suppress all node
+     * transforms for this update cycle.
+     * Useful for synchronizing updates in some cases.
+     */
     skipTransforms?: true;
+    /**
+     * A tag to identify this update, in an update listener, for instance.
+     * See also {@link $addUpdateTag}.
+     */
     tag?: UpdateTag | UpdateTag[];
+    /**
+     * If true, prevents this update from being batched, forcing it to
+     * run synchronously.
+     */
     discrete?: true;
     /** @internal */
     event?: undefined | UIEvent | Event | null;
@@ -42,9 +59,13 @@ export type EditorUpdateOptions = {
 export type EditorSetOptions = {
     tag?: string;
 };
-export type EditorFocusOptions = {
+export interface EditorFocusOptions {
+    /**
+     * Where to move selection when the editor is
+     * focused. Can be rootStart, rootEnd, or undefined. Defaults to rootEnd.
+     */
     defaultSelection?: 'rootStart' | 'rootEnd';
-};
+}
 export type EditorThemeClasses = {
     blockCursor?: EditorThemeClassName;
     characterLimit?: EditorThemeClassName;
@@ -123,11 +144,15 @@ export type HTMLConfig = {
     export?: DOMExportOutputMap;
     import?: DOMConversionMap;
 };
+/**
+ * A LexicalNode class or LexicalNodeReplacement configuration
+ */
+export type LexicalNodeConfig = Klass<LexicalNode> | LexicalNodeReplacement;
 export type CreateEditorArgs = {
     disableEvents?: boolean;
     editorState?: EditorState;
     namespace?: string;
-    nodes?: ReadonlyArray<Klass<LexicalNode> | LexicalNodeReplacement>;
+    nodes?: ReadonlyArray<LexicalNodeConfig>;
     onError?: ErrorHandler;
     parentEditor?: LexicalEditor;
     editable?: boolean;
@@ -141,10 +166,11 @@ export type RegisteredNode = {
     replace: null | ((node: LexicalNode) => LexicalNode);
     replaceWithKlass: null | Klass<LexicalNode>;
     exportDOM?: (editor: LexicalEditor, targetNode: LexicalNode) => DOMExportOutput;
+    sharedNodeState: SharedNodeState;
 };
 export type Transform<T extends LexicalNode> = (node: T) => void;
 export type ErrorHandler = (error: Error) => void;
-export type MutationListeners = Map<MutationListener, Klass<LexicalNode>>;
+export type MutationListeners = Map<MutationListener, Set<Klass<LexicalNode>>>;
 export type MutatedNodes = Map<Klass<LexicalNode>, Map<NodeKey, NodeMutation>>;
 export type NodeMutation = 'created' | 'updated' | 'destroyed';
 export interface MutationListenerOptions {
@@ -443,9 +469,9 @@ export declare class LexicalEditor {
      */
     registerMutationListener(klass: Klass<LexicalNode>, listener: MutationListener, options?: MutationListenerOptions): () => void;
     /** @internal */
-    private getRegisteredNode;
+    getRegisteredNode(klass: Klass<LexicalNode>): RegisteredNode;
     /** @internal */
-    private resolveRegisteredNodeAfterReplacements;
+    resolveRegisteredNodeAfterReplacements(registeredNode: RegisteredNode): RegisteredNode;
     /** @internal */
     private initializeMutationListener;
     /** @internal */
@@ -546,14 +572,6 @@ export declare class LexicalEditor {
      * where Lexical editor state can be safely mutated.
      * @param updateFn - A function that has access to writable editor state.
      * @param options - A bag of options to control the behavior of the update.
-     * @param options.onUpdate - A function to run once the update is complete.
-     * Useful for synchronizing updates in some cases.
-     * @param options.skipTransforms - Setting this to true will suppress all node
-     * transforms for this update cycle.
-     * @param options.tag - A tag to identify this update, in an update listener, for instance.
-     * Some tags are reserved by the core and control update behavior in different ways.
-     * @param options.discrete - If true, prevents this update from being batched, forcing it to
-     * run synchronously.
      */
     update(updateFn: () => void, options?: EditorUpdateOptions): void;
     /**
@@ -564,8 +582,6 @@ export declare class LexicalEditor {
      *
      * @param callbackFn - A function to run after the editor is focused.
      * @param options - A bag of options
-     * @param options.defaultSelection - Where to move selection when the editor is
-     * focused. Can be rootStart, rootEnd, or undefined. Defaults to rootEnd.
      */
     focus(callbackFn?: () => void, options?: EditorFocusOptions): void;
     /**

package/types/lexical/LexicalNode.ts

@@ -6,8 +6,9 @@
 
 import type { EditorConfig, Klass, KlassConstructor, LexicalEditor } from './LexicalEditor';
 import type { BaseSelection, RangeSelection } from './LexicalSelection';
-import { type DecoratorNode, ElementNode, NODE_STATE_KEY } from '.';
-import { type NodeState } from './LexicalNodeState';
+import { type DecoratorNode, type ElementNode, NODE_STATE_KEY } from '.';
+import { PROTOTYPE_CONFIG_METHOD } from './LexicalConstants';
+import { type NodeState, type NodeStateJSON, type Prettify, type RequiredNodeStateConfig } from './LexicalNodeState';
 export type NodeMap = Map<NodeKey, LexicalNode>;
 /**
  * The base type for all serialized nodes
@@ -17,8 +18,134 @@ export type SerializedLexicalNode = {
     type: string;
     /** A numeric version for this schema, defaulting to 1, but not generally recommended for use */
     version: number;
+    /**
+     * Any state persisted with the NodeState API that is not
+     * configured for flat storage
+     */
     [NODE_STATE_KEY]?: Record<string, unknown>;
 };
+/**
+ * EXPERIMENTAL
+ * The configuration of a node returned by LexicalNode.$config()
+ *
+ * @example
+ * ```ts
+ * class CustomText extends TextNode {
+ *   $config() {
+ *     return this.config('custom-text', {extends: TextNode}};
+ *   }
+ * }
+ * ```
+ */
+export interface StaticNodeConfigValue<T extends LexicalNode, Type extends string> {
+    /**
+     * The exact type of T.getType(), e.g. 'text' - the method itself must
+     * have a more generic 'string' type to be compatible wtih subclassing.
+     */
+    readonly type?: Type;
+    /**
+     * An alternative to the internal static transform() method
+     * that provides better type inference.
+     */
+    readonly $transform?: (node: T) => void;
+    /**
+     * An alternative to the static importJSON() method
+     * that provides better type inference.
+     */
+    readonly $importJSON?: (serializedNode: SerializedLexicalNode) => T;
+    /**
+     * An alternative to the static importDOM() method
+     */
+    readonly importDOM?: DOMConversionMap;
+    /**
+     * EXPERIMENTAL
+     *
+     * An array of RequiredNodeStateConfig to initialize your node with
+     * its state requirements. This may be used to configure serialization of
+     * that state.
+     *
+     * This function will be called (at most) once per editor initialization,
+     * directly on your node's prototype. It must not depend on any state
+     * initialized in the constructor.
+     *
+     * @example
+     * ```ts
+     * const flatState = createState("flat", {parse: parseNumber});
+     * const nestedState = createState("nested", {parse: parseNumber});
+     * class MyNode extends TextNode {
+     *   $config() {
+     *     return this.config(
+     *       'my-node',
+     *       {
+     *         extends: TextNode,
+     *         stateConfigs: [
+     *           { stateConfig: flatState, flat: true},
+     *           nestedState,
+     *         ]
+     *       },
+     *     );
+     *   }
+     * }
+     * ```
+     */
+    readonly stateConfigs?: readonly RequiredNodeStateConfig[];
+    /**
+     * If specified, this must be the exact superclass of the node. It is not
+     * checked at compile time and it is provided automatically at runtime.
+     *
+     * You would want to specify this when you are extending a node that
+     * has non-trivial configuration in its $config such
+     * as required state. If you do not specify this, the inferred
+     * types for your node class might be missing some of that.
+     */
+    readonly extends?: Klass<LexicalNode>;
+}
+/**
+ * This is the type of LexicalNode.$config() that can be
+ * overridden by subclasses.
+ */
+export type BaseStaticNodeConfig = {
+    readonly [K in string]?: StaticNodeConfigValue<LexicalNode, string>;
+};
+/**
+ * Used to extract the node and type from a StaticNodeConfigRecord
+ */
+export type StaticNodeConfig<T extends LexicalNode, Type extends string> = BaseStaticNodeConfig & {
+    readonly [K in Type]?: StaticNodeConfigValue<T, Type>;
+};
+/**
+ * Any StaticNodeConfigValue (for generics and collections)
+ */
+export type AnyStaticNodeConfigValue = StaticNodeConfigValue<any, any>;
+/**
+ * @internal
+ *
+ * This is the more specific type than BaseStaticNodeConfig that a subclass
+ * should return from $config()
+ */
+export type StaticNodeConfigRecord<Type extends string, Config extends AnyStaticNodeConfigValue> = BaseStaticNodeConfig & {
+    readonly [K in Type]?: Config;
+};
+/**
+ * Extract the type from a node based on its $config
+ *
+ * @example
+ * ```ts
+ * type TextNodeType = GetStaticNodeType<TextNode>;
+ *      // ? 'text'
+ * ```
+ */
+export type GetStaticNodeType<T extends LexicalNode> = ReturnType<T[typeof PROTOTYPE_CONFIG_METHOD]> extends StaticNodeConfig<T, infer Type> ? Type : string;
+/**
+ * The most precise type we can infer for the JSON that will
+ * be produced by T.exportJSON().
+ *
+ * Do not use this for the return type of T.exportJSON()! It must be
+ * a more generic type to be compatible with subclassing.
+ */
+export type LexicalExportJSON<T extends LexicalNode> = Prettify<Omit<ReturnType<T['exportJSON']>, 'type'> & {
+    type: GetStaticNodeType<T>;
+} & NodeStateJSON<T>>;
 /**
  * Omit the children, type, and version properties from the given SerializedLexicalNode definition.
  */
@@ -32,13 +159,26 @@ export interface LexicalPrivateDOM {
     __lexicalUnmanaged?: boolean | undefined;
 }
 export declare function $removeNode(nodeToRemove: LexicalNode, restoreSelection: boolean, preserveEmptyParent?: boolean): void;
+export type DOMConversionProp<T extends HTMLElement> = (node: T) => DOMConversion<T> | null;
+export type DOMConversionPropByTagName<K extends string> = DOMConversionProp<K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement>;
+export type DOMConversionTagNameMap<K extends string> = {
+    [NodeName in K]?: DOMConversionPropByTagName<NodeName>;
+};
+/**
+ * An identity function that will infer the type of DOM nodes
+ * based on tag names to make it easier to construct a
+ * DOMConversionMap.
+ */
+export declare function buildImportMap<K extends string>(importMap: {
+    [NodeName in K]: DOMConversionPropByTagName<NodeName>;
+}): DOMConversionMap;
 export type DOMConversion<T extends HTMLElement = HTMLElement> = {
     conversion: DOMConversionFn<T>;
     priority?: 0 | 1 | 2 | 3 | 4;
 };
 export type DOMConversionFn<T extends HTMLElement = HTMLElement> = (element: T) => DOMConversionOutput | null;
 export type DOMChildConversion = (lexicalNode: LexicalNode, parentLexicalNode: LexicalNode | null | undefined) => LexicalNode | null | undefined;
-export type DOMConversionMap<T extends HTMLElement = HTMLElement> = Record<NodeName, (node: T) => DOMConversion<T> | null>;
+export type DOMConversionMap<T extends HTMLElement = HTMLElement> = Record<NodeName, DOMConversionProp<T>>;
 type NodeName = string;
 export type DOMConversionOutput = {
     after?: (childLexicalNodes: Array<LexicalNode>) => Array<LexicalNode>;
@@ -79,6 +219,28 @@ export declare class LexicalNode {
      *
      */
     static clone(_data: unknown): LexicalNode;
+    /**
+     * Override this to implement the new static node configuration protocol,
+     * this method is called directly on the prototype and must not depend
+     * on anything initialized in the constructor. Generally it should be
+     * a trivial implementation.
+     *
+     * @example
+     * ```ts
+     * class MyNode extends TextNode {
+     *   $config() {
+     *     return this.config('my-node', {extends: TextNode});
+     *   }
+     * }
+     * ```
+     */
+    $config(): BaseStaticNodeConfig;
+    /**
+     * This is a convenience method for $config that
+     * aids in type inference. See {@link LexicalNode.$config}
+     * for example usage.
+     */
+    config<Type extends string, Config extends StaticNodeConfigValue<this, Type>>(type: Type, config: Config): StaticNodeConfigRecord<Type, Config>;
     /**
      * Perform any state updates on the clone of prevNode that are not already
      * handled by the constructor call in the static clone method. If you have

package/types/lexical/LexicalNodeState.ts

@@ -4,50 +4,8 @@
 // Type definitions based on Lexical
 // Original copyright: Meta Platforms, Inc. and affiliates.
 
-import type { LexicalNode } from './LexicalNode';
-import { NODE_STATE_KEY } from './LexicalConstants';
-/**
- * The return value of {@link createState}, for use with
- * {@link $getState} and {@link $setState}.
- */
-export declare class StateConfig<K extends string, V> {
-    /** The string key used when serializing this state to JSON */
-    readonly key: K;
-    /** The parse function from the StateValueConfig passed to createState */
-    readonly parse: (value?: unknown) => V;
-    /**
-     * The unparse function from the StateValueConfig passed to createState,
-     * with a default that is simply a pass-through that assumes the value is
-     * JSON serializable.
-     */
-    readonly unparse: (value: V) => unknown;
-    /**
-     * An equality function from the StateValueConfig, with a default of
-     * Object.is.
-     */
-    readonly isEqual: (a: V, b: V) => boolean;
-    /**
-     * The result of `stateValueConfig.parse(undefined)`, which is computed only
-     * once and used as the default value. When the current value `isEqual` to
-     * the `defaultValue`, it will not be serialized to JSON.
-     */
-    readonly defaultValue: V;
-    constructor(key: K, stateValueConfig: StateValueConfig<V>);
-}
-/**
- * For advanced use cases, using this type is not recommended unless
- * it is required (due to TypeScript's lack of features like
- * higher-kinded types).
- *
- * A {@link StateConfig} type with any key and any value that can be
- * used in situations where the key and value type can not be known,
- * such as in a generic constraint when working with a collection of
- * StateConfig.
- *
- * {@link StateConfigKey} and {@link StateConfigValue} will be
- * useful when this is used as a generic constraint.
- */
-export type AnyStateConfig = StateConfig<any, any>;
+import { type Klass, type LexicalNode, type LexicalNodeConfig, NODE_STATE_KEY, type Spread, type StaticNodeConfigRecord } from '.';
+import { PROTOTYPE_CONFIG_METHOD } from './LexicalConstants';
 /**
  * Get the value type (V) from a StateConfig
  */
@@ -61,6 +19,60 @@ export type StateConfigKey<S extends AnyStateConfig> = S extends StateConfig<inf
  * {@link $setState} or any user-defined wrappers around it.
  */
 export type ValueOrUpdater<V> = V | ((prevValue: V) => V);
+/**
+ * A type alias to make it easier to define setter methods on your node class
+ *
+ * @example
+ * ```ts
+ * const fooState = createState("foo", { parse: ... });
+ * class MyClass extends TextNode {
+ *   // ...
+ *   setFoo(valueOrUpdater: StateValueOrUpdater<typeof fooState>): this {
+ *     return $setState(this, fooState, valueOrUpdater);
+ *   }
+ * }
+ * ```
+ */
+export type StateValueOrUpdater<Cfg extends AnyStateConfig> = ValueOrUpdater<StateConfigValue<Cfg>>;
+export interface NodeStateConfig<S extends AnyStateConfig> {
+    stateConfig: S;
+    flat?: boolean;
+}
+export type RequiredNodeStateConfig = NodeStateConfig<AnyStateConfig> | AnyStateConfig;
+export type StateConfigJSON<S> = S extends StateConfig<infer K, infer V> ? {
+    [Key in K]?: V;
+} : Record<never, never>;
+export type RequiredNodeStateConfigJSON<Config extends RequiredNodeStateConfig, Flat extends boolean> = StateConfigJSON<Config extends NodeStateConfig<infer S> ? Spread<Config, {
+    flat: false;
+}> extends {
+    flat: Flat;
+} ? S : never : false extends Flat ? Config : never>;
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;
+export type CollectStateJSON<Tuple extends readonly RequiredNodeStateConfig[], Flat extends boolean> = UnionToIntersection<{
+    [K in keyof Tuple]: RequiredNodeStateConfigJSON<Tuple[K], Flat>;
+}[number]>;
+type GetStaticNodeConfig<T extends LexicalNode> = ReturnType<T[typeof PROTOTYPE_CONFIG_METHOD]> extends infer Record ? Record extends StaticNodeConfigRecord<infer Type, infer Config> ? Config & {
+    readonly type: Type;
+} : never : never;
+type GetStaticNodeConfigs<T extends LexicalNode> = GetStaticNodeConfig<T> extends infer OwnConfig ? OwnConfig extends never ? [] : OwnConfig extends {
+    extends: Klass<infer Parent>;
+} ? GetStaticNodeConfig<Parent> extends infer ParentNodeConfig ? ParentNodeConfig extends never ? [OwnConfig] : [OwnConfig, ...GetStaticNodeConfigs<Parent>] : OwnConfig : [OwnConfig] : [];
+type CollectStateConfigs<Configs> = Configs extends [
+    infer OwnConfig,
+    ...infer ParentConfigs
+] ? OwnConfig extends {
+    stateConfigs: infer StateConfigs;
+} ? StateConfigs extends readonly RequiredNodeStateConfig[] ? [...StateConfigs, ...CollectStateConfigs<ParentConfigs>] : CollectStateConfigs<ParentConfigs> : CollectStateConfigs<ParentConfigs> : [];
+export type GetNodeStateConfig<T extends LexicalNode> = CollectStateConfigs<GetStaticNodeConfigs<T>>;
+/**
+ * The NodeState JSON produced by this LexicalNode
+ */
+export type NodeStateJSON<T extends LexicalNode> = Prettify<{
+    [NODE_STATE_KEY]?: Prettify<CollectStateJSON<GetNodeStateConfig<T>, false>>;
+} & CollectStateJSON<GetNodeStateConfig<T>, true>>;
 /**
  * Configure a value to be used with StateConfig.
  *
@@ -140,6 +152,48 @@ export interface StateValueConfig<V> {
      */
     isEqual?: (a: V, b: V) => boolean;
 }
+/**
+ * The return value of {@link createState}, for use with
+ * {@link $getState} and {@link $setState}.
+ */
+export declare class StateConfig<K extends string, V> {
+    /** The string key used when serializing this state to JSON */
+    readonly key: K;
+    /** The parse function from the StateValueConfig passed to createState */
+    readonly parse: (value?: unknown) => V;
+    /**
+     * The unparse function from the StateValueConfig passed to createState,
+     * with a default that is simply a pass-through that assumes the value is
+     * JSON serializable.
+     */
+    readonly unparse: (value: V) => unknown;
+    /**
+     * An equality function from the StateValueConfig, with a default of
+     * Object.is.
+     */
+    readonly isEqual: (a: V, b: V) => boolean;
+    /**
+     * The result of `stateValueConfig.parse(undefined)`, which is computed only
+     * once and used as the default value. When the current value `isEqual` to
+     * the `defaultValue`, it will not be serialized to JSON.
+     */
+    readonly defaultValue: V;
+    constructor(key: K, stateValueConfig: StateValueConfig<V>);
+}
+/**
+ * For advanced use cases, using this type is not recommended unless
+ * it is required (due to TypeScript's lack of features like
+ * higher-kinded types).
+ *
+ * A {@link StateConfig} type with any key and any value that can be
+ * used in situations where the key and value type can not be known,
+ * such as in a generic constraint when working with a collection of
+ * StateConfig.
+ *
+ * {@link StateConfigKey} and {@link StateConfigValue} will be
+ * useful when this is used as a generic constraint.
+ */
+export type AnyStateConfig = StateConfig<any, any>;
 /**
  * Create a StateConfig for the given string key and StateValueConfig.
  *
@@ -154,21 +208,6 @@ export interface StateValueConfig<V> {
  * @returns a StateConfig
  */
 export declare function createState<K extends string, V>(key: K, valueConfig: StateValueConfig<V>): StateConfig<K, V>;
-/**
- * Given two versions of a node and a stateConfig, compare their state values
- * using `$getState(nodeVersion, stateConfig, 'direct')`.
- * If the values are equal according to `stateConfig.isEqual`, return `null`,
- * otherwise return `[value, prevValue]`.
- *
- * This is useful for implementing updateDOM. Note that the `'direct'`
- * version argument is used for both nodes.
- *
- * @param node Any LexicalNode
- * @param prevNode A previous version of node
- * @param stateConfig The configuration of the state to read
- * @returns `[value, prevValue]` if changed, otherwise `null`
- */
-export declare function $getStateChange<T extends LexicalNode, K extends string, V>(node: T, prevNode: T, stateConfig: StateConfig<K, V>): null | [value: V, prevValue: V];
 /**
  * The accessor for working with node state. This will read the value for the
  * state on the given node, and will return `stateConfig.defaultValue` if the
@@ -189,6 +228,21 @@ export declare function $getStateChange<T extends LexicalNode, K extends string,
  * @returns The current value from the state, or the default value provided by the configuration.
  */
 export declare function $getState<K extends string, V>(node: LexicalNode, stateConfig: StateConfig<K, V>, version?: 'latest' | 'direct'): V;
+/**
+ * Given two versions of a node and a stateConfig, compare their state values
+ * using `$getState(nodeVersion, stateConfig, 'direct')`.
+ * If the values are equal according to `stateConfig.isEqual`, return `null`,
+ * otherwise return `[value, prevValue]`.
+ *
+ * This is useful for implementing updateDOM. Note that the `'direct'`
+ * version argument is used for both nodes.
+ *
+ * @param node Any LexicalNode
+ * @param prevNode A previous version of node
+ * @param stateConfig The configuration of the state to read
+ * @returns `[value, prevValue]` if changed, otherwise `null`
+ */
+export declare function $getStateChange<T extends LexicalNode, K extends string, V>(node: T, prevNode: T, stateConfig: StateConfig<K, V>): null | [value: V, prevValue: V];
 /**
  * Set the state defined by stateConfig on node. Like with `React.useState`
  * you may directly specify the value or use an updater function that will
@@ -213,8 +267,29 @@ export declare function $getState<K extends string, V>(node: LexicalNode, stateC
  * @returns node
  */
 export declare function $setState<Node extends LexicalNode, K extends string, V>(node: Node, stateConfig: StateConfig<K, V>, valueOrUpdater: ValueOrUpdater<V>): Node;
+/**
+ * @internal
+ *
+ * Opaque state to be stored on the editor's RegisterNode for use by NodeState
+ */
+export type SharedNodeState = {
+    sharedConfigMap: SharedConfigMap;
+    flatKeys: Set<string>;
+};
+/**
+ * @internal
+ *
+ * Create the state to store on RegisteredNode
+ */
+export declare function createSharedNodeState(nodeConfig: LexicalNodeConfig): SharedNodeState;
 type KnownStateMap = Map<AnyStateConfig, unknown>;
 type UnknownStateRecord = Record<string, unknown>;
+/**
+ * @internal
+ *
+ * A Map of string keys to state configurations to be shared across nodes
+ * and/or node versions.
+ */
 type SharedConfigMap = Map<string, AnyStateConfig>;
 /**
  * @internal
@@ -248,8 +323,7 @@ export declare class NodeState<T extends LexicalNode> {
      * imported but has not been parsed yet.
      *
      * It stays here until a get state requires us to parse it, and since we
-     * then know the value is safe we move it to knownState and garbage collect
-     * it at the next version.
+     * then know the value is safe we move it to knownState.
      *
      * Note that since only string keys are used here, we can only allow this
      * state to pass-through on export or on the next version since there is
@@ -262,10 +336,11 @@ export declare class NodeState<T extends LexicalNode> {
     /**
      * @internal
      *
-     * This sharedConfigMap is preserved across all versions of a given node and
-     * remains writable. It is how keys are resolved to configuration.
+     * This sharedNodeState is preserved across all instances of a given
+     * node type in an editor and remains writable. It is how keys are resolved
+     * to configuration.
      */
-    readonly sharedConfigMap: SharedConfigMap;
+    readonly sharedNodeState: SharedNodeState;
     /**
      * @internal
      *
@@ -276,8 +351,16 @@ export declare class NodeState<T extends LexicalNode> {
     /**
      * @internal
      */
-    constructor(node: T, sharedConfigMap?: SharedConfigMap, unknownState?: undefined | UnknownStateRecord, knownState?: KnownStateMap, size?: number | undefined);
-    /** @internal */
+    constructor(node: T, sharedNodeState: SharedNodeState, unknownState?: undefined | UnknownStateRecord, knownState?: KnownStateMap, size?: number | undefined);
+    /**
+     * @internal
+     *
+     * Get the value from knownState, or parse it from unknownState
+     * if it contains the given key.
+     *
+     * Updates the sharedConfigMap when no known state is found.
+     * Updates unknownState and knownState when an unknownState is parsed.
+     */
     getValue<K extends string, V>(stateConfig: StateConfig<K, V>): V;
     /**
      * @internal
@@ -299,9 +382,7 @@ export declare class NodeState<T extends LexicalNode> {
      * specific entries in the future when nodes can declare what
      * their required StateConfigs are.
      */
-    toJSON(): {
-        [NODE_STATE_KEY]?: UnknownStateRecord;
-    };
+    toJSON(): NodeStateJSON<T>;
     /**
      * @internal
      *
@@ -357,6 +438,12 @@ export declare class NodeState<T extends LexicalNode> {
  * {@link $setState}. This is effectively the preamble for {@link $setState}.
  */
 export declare function $getWritableNodeState<T extends LexicalNode>(node: T): NodeState<T>;
+/**
+ * @internal
+ *
+ * Get the SharedNodeState for a node on this editor
+ */
+export declare function $getSharedNodeState<T extends LexicalNode>(node: T): SharedNodeState;
 /**
  * @internal
  *
@@ -375,5 +462,11 @@ export declare function $updateStateFromJSON<T extends LexicalNode>(node: T, unk
  * to determine when TextNode are being merged, not a lot of use cases
  * otherwise.
  */
-export declare function $nodeStatesAreEquivalent<T extends LexicalNode>(a: undefined | NodeState<T>, b: undefined | NodeState<T>): boolean;
+export declare function nodeStatesAreEquivalent<T extends LexicalNode>(a: undefined | NodeState<T>, b: undefined | NodeState<T>): boolean;
+/**
+ * @internal
+ *
+ * Clones the NodeState for a given node. Handles aliasing if the state references the from node.
+ */
+export declare function $cloneNodeState<T extends LexicalNode>(from: T, to: T): undefined | NodeState<T>;
 export {};

package/types/lexical/LexicalUtils.ts

@@ -6,16 +6,25 @@
 
 import type { CommandPayloadType, EditorThemeClasses, Klass, LexicalCommand, MutatedNodes, MutationListeners, NodeMutation, RegisteredNode, RegisteredNodes, Spread } from './LexicalEditor';
 import type { EditorState } from './LexicalEditorState';
-import type { LexicalNode, NodeKey, NodeMap } from './LexicalNode';
 import type { BaseSelection, PointType, RangeSelection } from './LexicalSelection';
 import type { RootNode } from './nodes/LexicalRootNode';
-import type { TextFormatType, TextNode } from './nodes/LexicalTextNode';
 import { DecoratorNode, ElementNode, LineBreakNode, UpdateTag } from '.';
 import { LexicalEditor } from './LexicalEditor';
+import { LexicalNode, type NodeKey, type NodeMap, type StaticNodeConfigValue } from './LexicalNode';
+import { type TextFormatType, TextNode } from './nodes/LexicalTextNode';
 export declare const emptyFunction: () => void;
+export declare function setPendingNodeToClone(pendingNode: null | LexicalNode): void;
+export declare function getPendingNodeToClone(): null | LexicalNode;
 export declare function resetRandomKey(): void;
 export declare function generateRandomKey(): string;
+/**
+ * @internal
+ */
 export declare function getRegisteredNodeOrThrow(editor: LexicalEditor, nodeType: string): RegisteredNode;
+/**
+ * @internal
+ */
+export declare function getRegisteredNode(editor: LexicalEditor, nodeType: string): undefined | RegisteredNode;
 export declare const isArray: (arg: any) => arg is any[];
 export declare const scheduleMicroTask: (fn: () => void) => void;
 export declare function $isSelectionCapturedInDecorator(node: Node): boolean;
@@ -190,7 +199,11 @@ type ShadowRootNode = Spread<{
 }, ElementNode>;
 export declare function $isRootOrShadowRoot(node: null | LexicalNode): node is RootNode | ShadowRootNode;
 /**
- * Returns a shallow clone of node with a new key
+ * Returns a shallow clone of node with a new key. All properties of the node
+ * will be copied to the new node (by `clone` and then `afterCloneFrom`),
+ * except those related to parent/sibling/child
+ * relationships in the `EditorState`. This means that the copy must be
+ * separately added to the document, and it will not have any children.
  *
  * @param node - The node to be copied.
  * @returns The copy of the node.
@@ -283,7 +296,7 @@ export declare function getCachedTypeToNodeMap(editorState: EditorState): TypeTo
  * do not try and use this function to duplicate or copy an existing node.
  *
  * Does not mutate the EditorState.
- * @param node - The node to be cloned.
+ * @param latestNode - The node to be cloned.
  * @returns The clone of the node.
  */
 export declare function $cloneWithProperties<T extends LexicalNode>(latestNode: T): T;
@@ -301,4 +314,38 @@ export declare function setDOMUnmanaged(elementDom: HTMLElement): void;
  * True if this DOM node was marked with {@link setDOMUnmanaged}
  */
 export declare function isDOMUnmanaged(elementDom: Node): boolean;
+/**
+ * @internal
+ */
+export declare function hasOwnStaticMethod(klass: Klass<LexicalNode>, k: keyof Klass<LexicalNode>): boolean;
+/**
+ * @internal
+ */
+export declare function hasOwnExportDOM(klass: Klass<LexicalNode>): boolean;
+/** @internal */
+export declare function getStaticNodeConfig(klass: Klass<LexicalNode>): {
+    ownNodeType: undefined | string;
+    ownNodeConfig: undefined | StaticNodeConfigValue<LexicalNode, string>;
+};
+/**
+ * Create an node from its class.
+ *
+ * Note that this will directly construct the final `withKlass` node type,
+ * and will ignore the deprecated `with` functions. This allows `$create` to
+ * skip any intermediate steps where the replaced node would be created and
+ * then immediately discarded (once per configured replacement of that node).
+ *
+ * This does not support any arguments to the constructor.
+ * Setters can be used to initialize your node, and they can
+ * be chained. You can of course write your own mutliple-argument functions
+ * to wrap that.
+ *
+ * @example
+ * ```ts
+ * function $createTokenText(text: string): TextNode {
+ *   return $create(TextNode).setTextContent(text).setMode('token');
+ * }
+ * ```
+ */
+export declare function $create<T extends LexicalNode>(klass: Klass<T>): T;
 export {};

package/types/lexical/list/LexicalListItemNode.ts

@@ -4,7 +4,7 @@
 // Type definitions based on Lexical
 // Original copyright: Meta Platforms, Inc. and affiliates.
 
-import type { BaseSelection, DOMConversionMap, DOMExportOutput, EditorConfig, LexicalNode, LexicalUpdateJSON, NodeKey, ParagraphNode, RangeSelection, SerializedElementNode, Spread } from './../';
+import type { BaseSelection, DOMExportOutput, EditorConfig, LexicalNode, LexicalUpdateJSON, NodeKey, ParagraphNode, RangeSelection, SerializedElementNode, Spread } from './../';
 import { ElementNode, LexicalEditor } from './../';
 export type SerializedListItemNode = Spread<{
     checked: boolean | undefined;
@@ -16,15 +16,17 @@ export declare class ListItemNode extends ElementNode {
     __value: number;
     /** @internal */
     __checked?: boolean;
-    static getType(): string;
-    static clone(node: ListItemNode): ListItemNode;
-    constructor(value?: number, checked?: boolean, key?: NodeKey);
+    /** @internal */
+    $config(): import('./../').StaticNodeConfigRecord<"listitem", {
+        $transform: (node: ListItemNode) => void;
+        extends: typeof ElementNode;
+        importDOM: import('./../').DOMConversionMap<HTMLElement>;
+    }>;
+    constructor(value?: number, checked?: undefined | boolean, key?: NodeKey);
+    afterCloneFrom(prevNode: this): void;
     createDOM(config: EditorConfig): HTMLElement;
     updateListItemDOM(prevNode: ListItemNode | null, dom: HTMLLIElement, config: EditorConfig): void;
     updateDOM(prevNode: ListItemNode, dom: HTMLElement, config: EditorConfig): boolean;
-    static transform(): (node: LexicalNode) => void;
-    static importDOM(): DOMConversionMap | null;
-    static importJSON(serializedNode: SerializedListItemNode): ListItemNode;
     updateFromJSON(serializedNode: LexicalUpdateJSON<SerializedListItemNode>): this;
     exportDOM(editor: LexicalEditor): DOMExportOutput;
     exportJSON(): SerializedListItemNode;

package/types/lexical/list/LexicalListNode.ts

@@ -4,7 +4,7 @@
 // Type definitions based on Lexical
 // Original copyright: Meta Platforms, Inc. and affiliates.
 
-import { DOMConversionMap, DOMExportOutput, EditorConfig, ElementNode, LexicalEditor, LexicalNode, LexicalUpdateJSON, NodeKey, SerializedElementNode, Spread } from './../';
+import { DOMExportOutput, EditorConfig, ElementNode, LexicalEditor, LexicalNode, LexicalUpdateJSON, NodeKey, SerializedElementNode, Spread } from './../';
 export type SerializedListNode = Spread<{
     listType: ListType;
     start: number;
@@ -20,9 +20,14 @@ export declare class ListNode extends ElementNode {
     __start: number;
     /** @internal */
     __listType: ListType;
-    static getType(): string;
-    static clone(node: ListNode): ListNode;
+    /** @internal */
+    $config(): import('./../').StaticNodeConfigRecord<"list", {
+        $transform: (node: ListNode) => void;
+        extends: typeof ElementNode;
+        importDOM: import('./../').DOMConversionMap<HTMLElement>;
+    }>;
     constructor(listType?: ListType, start?: number, key?: NodeKey);
+    afterCloneFrom(prevNode: this): void;
     getTag(): ListNodeTagType;
     setListType(type: ListType): this;
     getListType(): ListType;
@@ -30,9 +35,6 @@ export declare class ListNode extends ElementNode {
     setStart(start: number): this;
     createDOM(config: EditorConfig, _editor?: LexicalEditor): HTMLElement;
     updateDOM(prevNode: this, dom: HTMLElement, config: EditorConfig): boolean;
-    static transform(): (node: LexicalNode) => void;
-    static importDOM(): DOMConversionMap | null;
-    static importJSON(serializedNode: SerializedListNode): ListNode;
     updateFromJSON(serializedNode: LexicalUpdateJSON<SerializedListNode>): this;
     exportDOM(editor: LexicalEditor): DOMExportOutput;
     exportJSON(): SerializedListNode;