@codemirror/state
Advanced tools
@codemirror/state - npm Package Compare versions
Comparing version 0.18.0 to 0.18.1
@@ -0,1 +1,7 @@ | ||
| ## 0.18.1 (2021-03-10) | ||
| ### New features | ||
| The new `Compartment.get` method can be used to get the content of a compartment in a given state. | ||
| ## 0.18.0 (2021-03-03) | ||
@@ -2,0 +8,0 @@ |
| import { Text } from '@codemirror/text'; | ||
| export { Text } from '@codemirror/text'; | ||
| /** | ||
| Distinguishes different ways in which positions can be mapped. | ||
| */ | ||
| declare enum MapMode { | ||
| /** | ||
| Map a position to a valid new position, even when its context | ||
| was deleted. | ||
| */ | ||
| Simple = 0, | ||
| /** | ||
| Return null if deletion happens across the position. | ||
| */ | ||
| TrackDel = 1, | ||
| /** | ||
| Return null if the character _before_ the position is deleted. | ||
| */ | ||
| TrackBefore = 2, | ||
| /** | ||
| Return null if the character _after_ the position is deleted. | ||
| */ | ||
| TrackAfter = 3 | ||
| } | ||
| /** | ||
| A change description is a variant of [change set](https://codemirror.net/6/docs/ref/#state.ChangeSet) | ||
| that doesn't store the inserted text. As such, it can't be | ||
| applied, but is cheaper to store and manipulate. | ||
| */ | ||
| declare class ChangeDesc { | ||
| /** | ||
| The length of the document before the change. | ||
| */ | ||
| get length(): number; | ||
| /** | ||
| The length of the document after the change. | ||
| */ | ||
| get newLength(): number; | ||
| /** | ||
| False when there are actual changes in this set. | ||
| */ | ||
| get empty(): boolean; | ||
| /** | ||
| Iterate over the unchanged parts left by these changes. | ||
| */ | ||
| iterGaps(f: (posA: number, posB: number, length: number) => void): void; | ||
| /** | ||
| Iterate over the ranges changed by these changes. (See | ||
| [`ChangeSet.iterChanges`](https://codemirror.net/6/docs/ref/#state.ChangeSet.iterChanges) for a | ||
| variant that also provides you with the inserted text.) | ||
| When `individual` is true, adjacent changes (which are kept | ||
| separate for [position mapping](https://codemirror.net/6/docs/ref/#state.ChangeDesc.mapPos)) are | ||
| reported separately. | ||
| */ | ||
| iterChangedRanges(f: (fromA: number, toA: number, fromB: number, toB: number) => void, individual?: boolean): void; | ||
| /** | ||
| Get a description of the inverted form of these changes. | ||
| */ | ||
| get invertedDesc(): ChangeDesc; | ||
| /** | ||
| Compute the combined effect of applying another set of changes | ||
| after this one. The length of the document after this set should | ||
| match the length before `other`. | ||
| */ | ||
| composeDesc(other: ChangeDesc): ChangeDesc; | ||
| /** | ||
| Map this description, which should start with the same document | ||
| as `other`, over another set of changes, so that it can be | ||
| applied after it. When `before` is true, map as if the changes | ||
| in `other` happened before the ones in `this`. | ||
| */ | ||
| mapDesc(other: ChangeDesc, before?: boolean): ChangeDesc; | ||
| /** | ||
| Map a given position through these changes, to produce a | ||
| position pointing into the new document. | ||
| `assoc` indicates which side the position should be associated | ||
| with. When it is negative or zero, the mapping will try to keep | ||
| the position close to the character before it (if any), and will | ||
| move it before insertions at that point or replacements across | ||
| that point. When it is positive, the position is associated with | ||
| the character after it, and will be moved forward for insertions | ||
| at or replacements across the position. Defaults to -1. | ||
| `mode` determines whether deletions should be | ||
| [reported](https://codemirror.net/6/docs/ref/#state.MapMode). It defaults to | ||
| [`MapMode.Simple`](https://codemirror.net/6/docs/ref/#state.MapMode.Simple) (don't report | ||
| deletions). | ||
| */ | ||
| mapPos(pos: number, assoc?: number): number; | ||
| mapPos(pos: number, assoc: number, mode: MapMode): number | null; | ||
| /** | ||
| Check whether these changes touch a given range. When one of the | ||
| changes entirely covers the range, the string `"cover"` is | ||
| returned. | ||
| */ | ||
| touchesRange(from: number, to?: number): boolean | "cover"; | ||
| } | ||
| /** | ||
| This type is used as argument to | ||
| [`EditorState.changes`](https://codemirror.net/6/docs/ref/#state.EditorState.changes) and in the | ||
| [`changes` field](https://codemirror.net/6/docs/ref/#state.TransactionSpec.changes) of transaction | ||
| specs to succinctly describe document changes. It may either be a | ||
| plain object describing a change (a deletion, insertion, or | ||
| replacement, depending on which fields are present), a [change | ||
| set](https://codemirror.net/6/docs/ref/#state.ChangeSet), or an array of change specs. | ||
| */ | ||
| declare type ChangeSpec = { | ||
@@ -28,46 +115,216 @@ from: number; | ||
| } | ChangeSet | readonly ChangeSpec[]; | ||
| /** | ||
| A change set represents a group of modifications to a document. It | ||
| stores the document length, and can only be applied to documents | ||
| with exactly that length. | ||
| */ | ||
| declare class ChangeSet extends ChangeDesc { | ||
| /** | ||
| Apply the changes to a document, returning the modified | ||
| document. | ||
| */ | ||
| apply(doc: Text): Text; | ||
| mapDesc(other: ChangeDesc, before?: boolean): ChangeDesc; | ||
| /** | ||
| Given the document as it existed _before_ the changes, return a | ||
| change set that represents the inverse of this set, which could | ||
| be used to go from the document created by the changes back to | ||
| the document as it existed before the changes. | ||
| */ | ||
| invert(doc: Text): ChangeSet; | ||
| /** | ||
| Combine two subsequent change sets into a single set. `other` | ||
| must start in the document produced by `this`. If `this` goes | ||
| `docA` → `docB` and `other` represents `docB` → `docC`, the | ||
| returned value will represent the change `docA` → `docC`. | ||
| */ | ||
| compose(other: ChangeSet): ChangeSet; | ||
| /** | ||
| Given another change set starting in the same document, maps this | ||
| change set over the other, producing a new change set that can be | ||
| applied to the document produced by applying `other`. When | ||
| `before` is `true`, order changes as if `this` comes before | ||
| `other`, otherwise (the default) treat `other` as coming first. | ||
| Given two changes `A` and `B`, `A.compose(B.map(A))` and | ||
| `B.compose(A.map(B, true))` will produce the same document. This | ||
| provides a basic form of [operational | ||
| transformation](https://en.wikipedia.org/wiki/Operational_transformation), | ||
| and can be used for collaborative editing. | ||
| */ | ||
| map(other: ChangeDesc, before?: boolean): ChangeSet; | ||
| /** | ||
| Iterate over the changed ranges in the document, calling `f` for | ||
| each. | ||
| When `individual` is true, adjacent changes are reported | ||
| separately. | ||
| */ | ||
| iterChanges(f: (fromA: number, toA: number, fromB: number, toB: number, inserted: Text) => void, individual?: boolean): void; | ||
| /** | ||
| Get a [change description](https://codemirror.net/6/docs/ref/#state.ChangeDesc) for this change | ||
| set. | ||
| */ | ||
| get desc(): ChangeDesc; | ||
| /** | ||
| Serialize this change set to a JSON-representable value. | ||
| */ | ||
| toJSON(): any; | ||
| /** | ||
| Create a change set for the given changes, for a document of the | ||
| given length, using `lineSep` as line separator. | ||
| */ | ||
| static of(changes: ChangeSpec, length: number, lineSep?: string): ChangeSet; | ||
| /** | ||
| Create an empty changeset of the given length. | ||
| */ | ||
| static empty(length: number): ChangeSet; | ||
| /** | ||
| Create a changeset from its JSON representation (as produced by | ||
| [`toJSON`](https://codemirror.net/6/docs/ref/#state.ChangeSet.toJSON). | ||
| */ | ||
| static fromJSON(json: any): ChangeSet; | ||
| } | ||
| /** | ||
| A single selection range. When | ||
| [`allowMultipleSelections`](https://codemirror.net/6/docs/ref/#state.EditorState^allowMultipleSelections) | ||
| is enabled, a [selection](https://codemirror.net/6/docs/ref/#state.EditorSelection) may hold | ||
| multiple ranges. By default, selections hold exactly one range. | ||
| */ | ||
| declare class SelectionRange { | ||
| /** | ||
| The lower boundary of the range. | ||
| */ | ||
| readonly from: number; | ||
| /** | ||
| The upper boundary of the range. | ||
| */ | ||
| readonly to: number; | ||
| private flags; | ||
| /** | ||
| The anchor of the range—the side that doesn't move when you | ||
| extend it. | ||
| */ | ||
| get anchor(): number; | ||
| /** | ||
| The head of the range, which is moved when the range is | ||
| [extended](https://codemirror.net/6/docs/ref/#state.SelectionRange.extend). | ||
| */ | ||
| get head(): number; | ||
| /** | ||
| True when `anchor` and `head` are at the same position. | ||
| */ | ||
| get empty(): boolean; | ||
| /** | ||
| If this is a cursor that is explicitly associated with the | ||
| character on one of its sides, this returns the side. -1 means | ||
| the character before its position, 1 the character after, and 0 | ||
| means no association. | ||
| */ | ||
| get assoc(): -1 | 0 | 1; | ||
| /** | ||
| The bidirectional text level associated with this cursor, if | ||
| any. | ||
| */ | ||
| get bidiLevel(): number | null; | ||
| /** | ||
| The goal column (stored vertical offset) associated with a | ||
| cursor. This is used to preserve the vertical position when | ||
| [moving](https://codemirror.net/6/docs/ref/#view.EditorView.moveVertically) across | ||
| lines of different length. | ||
| */ | ||
| get goalColumn(): number | undefined; | ||
| /** | ||
| Map this range through a change, producing a valid range in the | ||
| updated document. | ||
| */ | ||
| map(change: ChangeDesc, assoc?: number): SelectionRange; | ||
| /** | ||
| Extend this range to cover at least `from` to `to`. | ||
| */ | ||
| extend(from: number, to?: number): SelectionRange; | ||
| /** | ||
| Compare this range to another range. | ||
| */ | ||
| eq(other: SelectionRange): boolean; | ||
| /** | ||
| Return a JSON-serializable object representing the range. | ||
| */ | ||
| toJSON(): any; | ||
| /** | ||
| Convert a JSON representation of a range to a `SelectionRange` | ||
| instance. | ||
| */ | ||
| static fromJSON(json: any): SelectionRange; | ||
| } | ||
| /** | ||
| An editor selection holds one or more selection ranges. | ||
| */ | ||
| declare class EditorSelection { | ||
| /** | ||
| The ranges in the selection, sorted by position. Ranges cannot | ||
| overlap (but they may touch, if they aren't empty). | ||
| */ | ||
| readonly ranges: readonly SelectionRange[]; | ||
| /** | ||
| The index of the _main_ range in the selection (which is | ||
| usually the range that was added last). | ||
| */ | ||
| readonly mainIndex: number; | ||
| /** | ||
| Map a selection through a change. Used to adjust the selection | ||
| position for changes. | ||
| */ | ||
| map(change: ChangeDesc, assoc?: number): EditorSelection; | ||
| /** | ||
| Compare this selection to another selection. | ||
| */ | ||
| eq(other: EditorSelection): boolean; | ||
| /** | ||
| Get the primary selection range. Usually, you should make sure | ||
| your code applies to _all_ ranges, by using methods like | ||
| [`changeByRange`](https://codemirror.net/6/docs/ref/#state.EditorState.changeByRange). | ||
| */ | ||
| get main(): SelectionRange; | ||
| /** | ||
| Make sure the selection only has one range. Returns a selection | ||
| holding only the main range from this selection. | ||
| */ | ||
| asSingle(): EditorSelection; | ||
| /** | ||
| Extend this selection with an extra range. | ||
| */ | ||
| addRange(range: SelectionRange, main?: boolean): EditorSelection; | ||
| /** | ||
| Replace a given range with another range, and then normalize the | ||
| selection to merge and sort ranges if necessary. | ||
| */ | ||
| replaceRange(range: SelectionRange, which?: number): EditorSelection; | ||
| /** | ||
| Convert this selection to an object that can be serialized to | ||
| JSON. | ||
| */ | ||
| toJSON(): any; | ||
| /** | ||
| Create a selection from a JSON representation. | ||
| */ | ||
| static fromJSON(json: any): EditorSelection; | ||
| /** | ||
| Create a selection holding a single range. | ||
| */ | ||
| static single(anchor: number, head?: number): EditorSelection; | ||
| /** | ||
| Sort and merge the given set of ranges, creating a valid | ||
| selection. | ||
| */ | ||
| static create(ranges: readonly SelectionRange[], mainIndex?: number): EditorSelection; | ||
| /** | ||
| Create a cursor selection range at the given position. You can | ||
| safely ignore the optional arguments in most situations. | ||
| */ | ||
| static cursor(pos: number, assoc?: number, bidiLevel?: number, goalColumn?: number): SelectionRange; | ||
| /** | ||
| Create a selection range. | ||
| */ | ||
| static range(anchor: number, head: number, goalColumn?: number): SelectionRange; | ||
@@ -77,15 +334,78 @@ } | ||
| declare type FacetConfig<Input, Output> = { | ||
| /** | ||
| How to combine the input values into a single output value. When | ||
| not given, the array of input values becomes the output. This | ||
| will immediately be called on creating the facet, with an empty | ||
| array, to compute the facet's default value when no inputs are | ||
| present. | ||
| */ | ||
| combine?: (value: readonly Input[]) => Output; | ||
| /** | ||
| How to compare output values to determine whether the value of | ||
| the facet changed. Defaults to comparing by `===` or, if no | ||
| `combine` function was given, comparing each element of the | ||
| array with `===`. | ||
| */ | ||
| compare?: (a: Output, b: Output) => boolean; | ||
| /** | ||
| How to compare input values to avoid recomputing the output | ||
| value when no inputs changed. Defaults to comparing with `===`. | ||
| */ | ||
| compareInput?: (a: Input, b: Input) => boolean; | ||
| /** | ||
| Static facets can not contain dynamic inputs. | ||
| */ | ||
| static?: boolean; | ||
| /** | ||
| If given, these extension(s) will be added to any state where | ||
| this facet is provided. (Note that, while a facet's default | ||
| value can be read from a state even if the facet wasn't present | ||
| in the state at all, these extensions won't be added in that | ||
| situation.) | ||
| */ | ||
| enables?: Extension; | ||
| }; | ||
| /** | ||
| A facet is a labeled value that is associated with an editor | ||
| state. It takes inputs from any number of extensions, and combines | ||
| those into a single output value. | ||
| Examples of facets are the [theme](https://codemirror.net/6/docs/ref/#view.EditorView^theme) styles | ||
| associated with an editor or the [tab | ||
| size](https://codemirror.net/6/docs/ref/#state.EditorState^tabSize) (which is reduced to a single | ||
| value, using the input with the hightest precedence). | ||
| */ | ||
| declare class Facet<Input, Output = readonly Input[]> { | ||
| private isStatic; | ||
| private constructor(); | ||
| /** | ||
| Define a new facet. | ||
| */ | ||
| static define<Input, Output = readonly Input[]>(config?: FacetConfig<Input, Output>): Facet<Input, Output>; | ||
| /** | ||
| Returns an extension that adds the given value for this facet. | ||
| */ | ||
| of(value: Input): Extension; | ||
| /** | ||
| Create an extension that computes a value for the facet from a | ||
| state. You must take care to declare the parts of the state that | ||
| this value depends on, since your function is only called again | ||
| for a new state when one of those parts changed. | ||
| In most cases, you'll want to use the | ||
| [`provide`](https://codemirror.net/6/docs/ref/#state.StateField^define^config.provide) option when | ||
| defining a field instead. | ||
| */ | ||
| compute(deps: readonly Slot<any>[], get: (state: EditorState) => Input): Extension; | ||
| /** | ||
| Create an extension that computes zero or more values for this | ||
| facet from a state. | ||
| */ | ||
| computeN(deps: readonly Slot<any>[], get: (state: EditorState) => readonly Input[]): Extension; | ||
| /** | ||
| Shorthand method for registering a facet source with a state | ||
| field as input. If the field's type corresponds to this facet's | ||
| input type, the getter function can be omitted. If given, it | ||
| will be used to retrieve the input from the field value. | ||
| */ | ||
| from(field: StateField<Input>): Extension; | ||
@@ -96,9 +416,43 @@ from<T>(field: StateField<T>, get: (value: T) => Input): Extension; | ||
| declare type StateFieldSpec<Value> = { | ||
| /** | ||
| Creates the initial value for the field when a state is created. | ||
| */ | ||
| create: (state: EditorState) => Value; | ||
| /** | ||
| Compute a new value from the field's previous value and a | ||
| [transaction](https://codemirror.net/6/docs/ref/#state.Transaction). | ||
| */ | ||
| update: (value: Value, transaction: Transaction) => Value; | ||
| /** | ||
| Compare two values of the field, returning `true` when they are | ||
| the same. This is used to avoid recomputing facets that depend | ||
| on the field when its value did not change. Defaults to using | ||
| `===`. | ||
| */ | ||
| compare?: (a: Value, b: Value) => boolean; | ||
| /** | ||
| Provide values for facets based on the value of this field. The | ||
| given function will be called once with the initialized field. It | ||
| will usually want to call some facet's | ||
| [`from`](https://codemirror.net/6/docs/ref/#state.Facet.from) method to create facet inputs from | ||
| this field, but can also return other extensions that should be | ||
| enabled by this field. | ||
| */ | ||
| provide?: (field: StateField<Value>) => Extension; | ||
| /** | ||
| A function used to serialize this field's content to JSON. Only | ||
| necessary when this field is included in the argument to | ||
| [`EditorState.toJSON`](https://codemirror.net/6/docs/ref/#state.EditorState.toJSON). | ||
| */ | ||
| toJSON?: (value: Value, state: EditorState) => any; | ||
| /** | ||
| A function that deserializes the JSON representation of this | ||
| field's content. | ||
| */ | ||
| fromJSON?: (json: any, state: EditorState) => Value; | ||
| }; | ||
| /** | ||
| Fields can store additional information in an editor state, and | ||
| keep it in sync with the rest of the state. | ||
| */ | ||
| declare class StateField<Value> { | ||
@@ -109,48 +463,203 @@ private createF; | ||
| private constructor(); | ||
| /** | ||
| Define a state field. | ||
| */ | ||
| static define<Value>(config: StateFieldSpec<Value>): StateField<Value>; | ||
| private create; | ||
| /** | ||
| Returns an extension that enables this field and overrides the | ||
| way it is initialized. Can be useful when you need to provide a | ||
| non-default starting value for the field. | ||
| */ | ||
| init(create: (state: EditorState) => Value): Extension; | ||
| extension: Extension; | ||
| /** | ||
| State field instances can be used as | ||
| [`Extension`](https://codemirror.net/6/docs/ref/#state.Extension) values to enable the field in a | ||
| given state. | ||
| */ | ||
| get extension(): Extension; | ||
| } | ||
| /** | ||
| Extension values can be | ||
| [provided](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions) when creating a | ||
| state to attach various kinds of configuration and behavior | ||
| information. They can either be built-in extension-providing | ||
| objects, such as [state fields](https://codemirror.net/6/docs/ref/#state.StateField) or [facet | ||
| providers](https://codemirror.net/6/docs/ref/#state.Facet.of), or objects with an extension in its | ||
| `extension` property. Extensions can be nested in arrays | ||
| arbitrarily deep—they will be flattened when processed. | ||
| */ | ||
| declare type Extension = { | ||
| extension: Extension; | ||
| } | readonly Extension[]; | ||
| /** | ||
| By default extensions are registered in the order they are found | ||
| in the flattened form of nested array that was provided. | ||
| Individual extension values can be assigned a precedence to | ||
| override this. Extensions that do not have a precedence set get | ||
| the precedence of the nearest parent with a precedence, or | ||
| [`default`](https://codemirror.net/6/docs/ref/#state.Prec.default) if there is no such parent. The | ||
| final ordering of extensions is determined by first sorting by | ||
| precedence and then by order within each precedence. | ||
| */ | ||
| declare const Prec: { | ||
| /** | ||
| A precedence below the default precedence, which will cause | ||
| default-precedence extensions to override it even if they are | ||
| specified later in the extension ordering. | ||
| */ | ||
| fallback: (ext: Extension) => Extension; | ||
| /** | ||
| The regular default precedence. | ||
| */ | ||
| default: (ext: Extension) => Extension; | ||
| /** | ||
| A higher-than-default precedence. | ||
| */ | ||
| extend: (ext: Extension) => Extension; | ||
| /** | ||
| Precedence above the `default` and `extend` precedences. | ||
| */ | ||
| override: (ext: Extension) => Extension; | ||
| }; | ||
| /** | ||
| Extension compartments can be used to make a configuration | ||
| dynamic. By [wrapping](https://codemirror.net/6/docs/ref/#state.Compartment.of) part of your | ||
| configuration in a compartment, you can later | ||
| [replace](https://codemirror.net/6/docs/ref/#state.Compartment.reconfigure) that part through a | ||
| transaction. | ||
| */ | ||
| declare class Compartment { | ||
| /** | ||
| Create an instance of this compartment to add to your [state | ||
| configuration](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions). | ||
| */ | ||
| of(ext: Extension): Extension; | ||
| /** | ||
| Create an [effect](https://codemirror.net/6/docs/ref/#state.TransactionSpec.effects) that | ||
| reconfigures this compartment. | ||
| */ | ||
| reconfigure(content: Extension): StateEffect<unknown>; | ||
| /** | ||
| Get the current content of the compartment in the state, or | ||
| `undefined` if it isn't present. | ||
| */ | ||
| get(state: EditorState): Extension | undefined; | ||
| } | ||
| /** | ||
| Annotations are tagged values that are used to add metadata to | ||
| transactions in an extensible way. They should be used to model | ||
| things that effect the entire transaction (such as its [time | ||
| stamp](https://codemirror.net/6/docs/ref/#state.Transaction^time) or information about its | ||
| [origin](https://codemirror.net/6/docs/ref/#state.Transaction^userEvent)). For effects that happen | ||
| _alongside_ the other changes made by the transaction, [state | ||
| effects](https://codemirror.net/6/docs/ref/#state.StateEffect) are more appropriate. | ||
| */ | ||
| declare class Annotation<T> { | ||
| /** | ||
| The annotation type. | ||
| */ | ||
| readonly type: AnnotationType<T>; | ||
| /** | ||
| The value of this annotation. | ||
| */ | ||
| readonly value: T; | ||
| /** | ||
| Define a new type of annotation. | ||
| */ | ||
| static define<T>(): AnnotationType<T>; | ||
| private _isAnnotation; | ||
| } | ||
| /** | ||
| Marker that identifies a type of [annotation](https://codemirror.net/6/docs/ref/#state.Annotation). | ||
| */ | ||
| declare class AnnotationType<T> { | ||
| /** | ||
| Create an instance of this annotation. | ||
| */ | ||
| of(value: T): Annotation<T>; | ||
| } | ||
| interface StateEffectSpec<Value> { | ||
| /** | ||
| Provides a way to map an effect like this through a position | ||
| mapping. When not given, the effects will simply not be mapped. | ||
| When the function returns `undefined`, that means the mapping | ||
| deletes the effect. | ||
| */ | ||
| map?: (value: Value, mapping: ChangeDesc) => Value | undefined; | ||
| } | ||
| /** | ||
| Representation of a type of state effect. Defined with | ||
| [`StateEffect.define`](https://codemirror.net/6/docs/ref/#state.StateEffect^define). | ||
| */ | ||
| declare class StateEffectType<Value> { | ||
| /** | ||
| @internal | ||
| */ | ||
| readonly map: (value: any, mapping: ChangeDesc) => any | undefined; | ||
| /** | ||
| Create a [state effect](https://codemirror.net/6/docs/ref/#state.StateEffect) instance of this | ||
| type. | ||
| */ | ||
| of(value: Value): StateEffect<Value>; | ||
| } | ||
| /** | ||
| State effects can be used to represent additional effects | ||
| associated with a [transaction](https://codemirror.net/6/docs/ref/#state.Transaction.effects). They | ||
| are often useful to model changes to custom [state | ||
| fields](https://codemirror.net/6/docs/ref/#state.StateField), when those changes aren't implicit in | ||
| document or selection changes. | ||
| */ | ||
| declare class StateEffect<Value> { | ||
| /** | ||
| The value of this effect. | ||
| */ | ||
| readonly value: Value; | ||
| /** | ||
| Map this effect through a position mapping. Will return | ||
| `undefined` when that ends up deleting the effect. | ||
| */ | ||
| map(mapping: ChangeDesc): StateEffect<Value> | undefined; | ||
| /** | ||
| Tells you whether this effect object is of a given | ||
| [type](https://codemirror.net/6/docs/ref/#state.StateEffectType). | ||
| */ | ||
| is<T>(type: StateEffectType<T>): this is StateEffect<T>; | ||
| /** | ||
| Define a new effect type. The type parameter indicates the type | ||
| of values that his effect holds. | ||
| */ | ||
| static define<Value = null>(spec?: StateEffectSpec<Value>): StateEffectType<Value>; | ||
| /** | ||
| Map an array of effects through a change set. | ||
| */ | ||
| static mapEffects(effects: readonly StateEffect<any>[], mapping: ChangeDesc): readonly StateEffect<any>[]; | ||
| /** | ||
| This effect can be used to reconfigure the root extensions of | ||
| the editor. Doing this will discard any extensions | ||
| [appended](https://codemirror.net/6/docs/ref/#state.StateEffect^appendConfig), but does not reset | ||
| the content of [reconfigured](https://codemirror.net/6/docs/ref/#state.Compartment.reconfigure) | ||
| compartments. | ||
| */ | ||
| static reconfigure: StateEffectType<Extension>; | ||
| /** | ||
| Append extensions to the top-level configuration of the editor. | ||
| */ | ||
| static appendConfig: StateEffectType<Extension>; | ||
| } | ||
| /** | ||
| Describes a [transaction](https://codemirror.net/6/docs/ref/#state.Transaction) when calling the | ||
| [`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update) method. | ||
| */ | ||
| interface TransactionSpec { | ||
| /** | ||
| The changes to the document made by this transaction. | ||
| */ | ||
| changes?: ChangeSpec; | ||
| /** | ||
| When set, this transaction explicitly updates the selection. | ||
| Offsets in this selection should refer to the document as it is | ||
| _after_ the transaction. | ||
| */ | ||
| selection?: EditorSelection | { | ||
@@ -160,33 +669,165 @@ anchor: number; | ||
| }; | ||
| /** | ||
| Attach [state effects](https://codemirror.net/6/docs/ref/#state.StateEffect) to this transaction. | ||
| Again, when they contain positions and this same spec makes | ||
| changes, those positions should refer to positions in the | ||
| updated document. | ||
| */ | ||
| effects?: StateEffect<any> | readonly StateEffect<any>[]; | ||
| /** | ||
| Set [annotations](https://codemirror.net/6/docs/ref/#state.Annotation) for this transaction. | ||
| */ | ||
| annotations?: Annotation<any> | readonly Annotation<any>[]; | ||
| /** | ||
| When set to `true`, the transaction is marked as needing to | ||
| scroll the current selection into view. | ||
| */ | ||
| scrollIntoView?: boolean; | ||
| /** | ||
| By default, transactions can be modified by [change | ||
| filters](https://codemirror.net/6/docs/ref/#state.EditorState^changeFilter) and [transaction | ||
| filters](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter). You can set this | ||
| to `false` to disable that. | ||
| */ | ||
| filter?: boolean; | ||
| /** | ||
| Normally, when multiple specs are combined (for example by | ||
| [`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update)), the | ||
| positions in `changes` are taken to refer to the document | ||
| positions in the initial document. When a spec has `sequental` | ||
| set to true, its positions will be taken to refer to the | ||
| document created by the specs before it instead. | ||
| */ | ||
| sequential?: boolean; | ||
| } | ||
| /** | ||
| Changes to the editor state are grouped into transactions. | ||
| Typically, a user action creates a single transaction, which may | ||
| contain any number of document changes, may change the selection, | ||
| or have other effects. Create a transaction by calling | ||
| [`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update). | ||
| */ | ||
| declare class Transaction { | ||
| /** | ||
| The state from which the transaction starts. | ||
| */ | ||
| readonly startState: EditorState; | ||
| /** | ||
| The document changes made by this transaction. | ||
| */ | ||
| readonly changes: ChangeSet; | ||
| /** | ||
| The selection set by this transaction, or undefined if it | ||
| doesn't explicitly set a selection. | ||
| */ | ||
| readonly selection: EditorSelection | undefined; | ||
| /** | ||
| The effects added to the transaction. | ||
| */ | ||
| readonly effects: readonly StateEffect<any>[]; | ||
| /** | ||
| Whether the selection should be scrolled into view after this | ||
| transaction is dispatched. | ||
| */ | ||
| readonly scrollIntoView: boolean; | ||
| /** | ||
| The new document produced by the transaction. Contrary to | ||
| [`.state`](https://codemirror.net/6/docs/ref/#state.Transaction.state)`.doc`, accessing this won't | ||
| force the entire new state to be computed right away, so it is | ||
| recommended that [transaction | ||
| filters](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter) use this getter | ||
| when they need to look at the new document. | ||
| */ | ||
| get newDoc(): Text; | ||
| /** | ||
| The new selection produced by the transaction. If | ||
| [`this.selection`](https://codemirror.net/6/docs/ref/#state.Transaction.selection) is undefined, | ||
| this will [map](https://codemirror.net/6/docs/ref/#state.EditorSelection.map) the start state's | ||
| current selection through the changes made by the transaction. | ||
| */ | ||
| get newSelection(): EditorSelection; | ||
| /** | ||
| The new state created by the transaction. Computed on demand | ||
| (but retained for subsequent access), so itis recommended not to | ||
| access it in [transaction | ||
| filters](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter) when possible. | ||
| */ | ||
| get state(): EditorState; | ||
| /** | ||
| Get the value of the given annotation type, if any. | ||
| */ | ||
| annotation<T>(type: AnnotationType<T>): T | undefined; | ||
| /** | ||
| Indicates whether the transaction changed the document. | ||
| */ | ||
| get docChanged(): boolean; | ||
| /** | ||
| Indicates whether this transaction reconfigures the state | ||
| (through a [configuration compartment](https://codemirror.net/6/docs/ref/#state.Compartment) or | ||
| with a top-level configuration | ||
| [effect](https://codemirror.net/6/docs/ref/#state.StateEffect^reconfigure). | ||
| */ | ||
| get reconfigured(): boolean; | ||
| /** | ||
| Annotation used to store transaction timestamps. | ||
| */ | ||
| static time: AnnotationType<number>; | ||
| /** | ||
| Annotation used to associate a transaction with a user interface | ||
| event. The view will set this to... | ||
| - `"input"` when the user types text | ||
| - `"delete"` when the user deletes the selection or text near the selection | ||
| - `"keyboardselection"` when moving the selection via the keyboard | ||
| - `"pointerselection"` when moving the selection through the pointing device | ||
| - `"paste"` when pasting content | ||
| - `"cut"` when cutting | ||
| - `"drop"` when content is inserted via drag-and-drop | ||
| */ | ||
| static userEvent: AnnotationType<string>; | ||
| /** | ||
| Annotation indicating whether a transaction should be added to | ||
| the undo history or not. | ||
| */ | ||
| static addToHistory: AnnotationType<boolean>; | ||
| } | ||
| /** | ||
| The categories produced by a [character | ||
| categorizer](https://codemirror.net/6/docs/ref/#state.EditorState.charCategorizer). These are used | ||
| do things like selecting by word. | ||
| */ | ||
| declare enum CharCategory { | ||
| /** | ||
| Word characters. | ||
| */ | ||
| Word = 0, | ||
| /** | ||
| Whitespace. | ||
| */ | ||
| Space = 1, | ||
| /** | ||
| Anything else. | ||
| */ | ||
| Other = 2 | ||
| } | ||
| /** | ||
| Options passed when [creating](https://codemirror.net/6/docs/ref/#state.EditorState^create) an | ||
| editor state. | ||
| */ | ||
| interface EditorStateConfig { | ||
| /** | ||
| The initial document. Defaults to an empty document. Can be | ||
| provided either as a plain string (which will be split into | ||
| lines according to the value of the [`lineSeparator` | ||
| facet](https://codemirror.net/6/docs/ref/#state.EditorState^lineSeparator)), or an instance of | ||
| the [`Text`](https://codemirror.net/6/docs/ref/#text.Text) class (which is what the state will use | ||
| to represent the document). | ||
| */ | ||
| doc?: string | Text; | ||
| /** | ||
| The starting selection. Defaults to a cursor at the very start | ||
| of the document. | ||
| */ | ||
| selection?: EditorSelection | { | ||
@@ -196,10 +837,52 @@ anchor: number; | ||
| }; | ||
| /** | ||
| [Extension(s)](https://codemirror.net/6/docs/ref/#state.Extension) to associate with this state. | ||
| */ | ||
| extensions?: Extension; | ||
| } | ||
| /** | ||
| The editor state class is a persistent (immutable) data structure. | ||
| To update a state, you [create](https://codemirror.net/6/docs/ref/#state.EditorState.update) a | ||
| [transaction](https://codemirror.net/6/docs/ref/#state.Transaction), which produces a _new_ state | ||
| instance, without modifying the original object. | ||
| As such, _never_ mutate properties of a state directly. That'll | ||
| just break things. | ||
| */ | ||
| declare class EditorState { | ||
| /** | ||
| The current document. | ||
| */ | ||
| readonly doc: Text; | ||
| /** | ||
| The current selection. | ||
| */ | ||
| readonly selection: EditorSelection; | ||
| /** | ||
| Retrieve the value of a [state field](https://codemirror.net/6/docs/ref/#state.StateField). Throws | ||
| an error when the state doesn't have that field, unless you pass | ||
| `false` as second parameter. | ||
| */ | ||
| field<T>(field: StateField<T>): T; | ||
| field<T>(field: StateField<T>, require: false): T | undefined; | ||
| /** | ||
| Create a [transaction](https://codemirror.net/6/docs/ref/#state.Transaction) that updates this | ||
| state. Any number of [transaction specs](https://codemirror.net/6/docs/ref/#state.TransactionSpec) | ||
| can be passed. Unless | ||
| [`sequential`](https://codemirror.net/6/docs/ref/#state.TransactionSpec.sequential) is set, the | ||
| [changes](https://codemirror.net/6/docs/ref/#state.TransactionSpec.changes) (if any) of each spec | ||
| are assumed to start in the _current_ document (not the document | ||
| produced by previous specs), and its | ||
| [selection](https://codemirror.net/6/docs/ref/#state.TransactionSpec.selection) and | ||
| [effects](https://codemirror.net/6/docs/ref/#state.TransactionSpec.effects) are assumed to refer | ||
| to the document created by its _own_ changes. The resulting | ||
| transaction contains the combined effect of all the different | ||
| specs. For [selection](https://codemirror.net/6/docs/ref/#state.TransactionSpec.selection), later | ||
| specs take precedence over earlier ones. | ||
| */ | ||
| update(...specs: readonly TransactionSpec[]): Transaction; | ||
| /** | ||
| Create a [transaction spec](https://codemirror.net/6/docs/ref/#state.TransactionSpec) that | ||
| replaces every selection range with the given content. | ||
| */ | ||
| replaceSelection(text: string | Text): { | ||
@@ -210,2 +893,13 @@ changes: ChangeSet; | ||
| }; | ||
| /** | ||
| Create a set of changes and a new selection by running the given | ||
| function for each range in the active selection. The function | ||
| can return an optional set of changes (in the coordinate space | ||
| of the start document), plus an updated range (in the coordinate | ||
| space of the document produced by the call's own changes). This | ||
| method will merge all the changes and ranges into a single | ||
| changeset and selection, and return it as a [transaction | ||
| spec](https://codemirror.net/6/docs/ref/#state.TransactionSpec), which can be passed to | ||
| [`update`](https://codemirror.net/6/docs/ref/#state.EditorState.update). | ||
| */ | ||
| changeByRange(f: (range: SelectionRange) => { | ||
@@ -220,18 +914,87 @@ range: SelectionRange; | ||
| }; | ||
| /** | ||
| Create a [change set](https://codemirror.net/6/docs/ref/#state.ChangeSet) from the given change | ||
| description, taking the state's document length and line | ||
| separator into account. | ||
| */ | ||
| changes(spec?: ChangeSpec): ChangeSet; | ||
| /** | ||
| Using the state's [line | ||
| separator](https://codemirror.net/6/docs/ref/#state.EditorState^lineSeparator), create a | ||
| [`Text`](https://codemirror.net/6/docs/ref/#text.Text) instance from the given string. | ||
| */ | ||
| toText(string: string): Text; | ||
| /** | ||
| Return the given range of the document as a string. | ||
| */ | ||
| sliceDoc(from?: number, to?: number): string; | ||
| /** | ||
| Get the value of a state [facet](https://codemirror.net/6/docs/ref/#state.Facet). | ||
| */ | ||
| facet<Output>(facet: Facet<any, Output>): Output; | ||
| /** | ||
| Convert this state to a JSON-serializable object. When custom | ||
| fields should be serialized, you can pass them in as an object | ||
| mapping property names (in the resulting object, which should | ||
| not use `doc` or `selection`) to fields. | ||
| */ | ||
| toJSON(fields?: { | ||
| [prop: string]: StateField<any>; | ||
| }): any; | ||
| /** | ||
| Deserialize a state from its JSON representation. When custom | ||
| fields should be deserialized, pass the same object you passed | ||
| to [`toJSON`](https://codemirror.net/6/docs/ref/#state.EditorState.toJSON) when serializing as | ||
| third argument. | ||
| */ | ||
| static fromJSON(json: any, config?: EditorStateConfig, fields?: { | ||
| [prop: string]: StateField<any>; | ||
| }): EditorState; | ||
| /** | ||
| Create a new state. You'll usually only need this when | ||
| initializing an editor—updated states are created by applying | ||
| transactions. | ||
| */ | ||
| static create(config?: EditorStateConfig): EditorState; | ||
| /** | ||
| A facet that, when enabled, causes the editor to allow multiple | ||
| ranges to be selected. Be careful though, because by default the | ||
| editor relies on the native DOM selection, which cannot handle | ||
| multiple selections. An extension like | ||
| [`drawSelection`](https://codemirror.net/6/docs/ref/#view.drawSelection) can be used to make | ||
| secondary selections visible to the user. | ||
| */ | ||
| static allowMultipleSelections: Facet<boolean, boolean>; | ||
| /** | ||
| Configures the tab size to use in this state. The first | ||
| (highest-precedence) value of the facet is used. If no value is | ||
| given, this defaults to 4. | ||
| */ | ||
| static tabSize: Facet<number, number>; | ||
| /** | ||
| The size (in columns) of a tab in the document, determined by | ||
| the [`tabSize`](https://codemirror.net/6/docs/ref/#state.EditorState^tabSize) facet. | ||
| */ | ||
| get tabSize(): number; | ||
| /** | ||
| The line separator to use. By default, any of `"\n"`, `"\r\n"` | ||
| and `"\r"` is treated as a separator when splitting lines, and | ||
| lines are joined with `"\n"`. | ||
| When you configure a value here, only that precise separator | ||
| will be used, allowing you to round-trip documents through the | ||
| editor without normalizing line separators. | ||
| */ | ||
| static lineSeparator: Facet<string, string | undefined>; | ||
| /** | ||
| Get the proper [line-break](https://codemirror.net/6/docs/ref/#state.EditorState^lineSeparator) | ||
| string for this state. | ||
| */ | ||
| get lineBreak(): string; | ||
| /** | ||
| Registers translation phrases. The | ||
| [`phrase`](https://codemirror.net/6/docs/ref/#state.EditorState.phrase) method will look through | ||
| all objects registered with this facet to find translations for | ||
| its argument. | ||
| */ | ||
| static phrases: Facet<{ | ||
@@ -242,3 +1005,12 @@ [key: string]: string; | ||
| }[]>; | ||
| /** | ||
| Look up a translation for the given phrase (via the | ||
| [`phrases`](https://codemirror.net/6/docs/ref/#state.EditorState^phrases) facet), or return the | ||
| original string if no translation is found. | ||
| */ | ||
| phrase(phrase: string): string; | ||
| /** | ||
| A facet used to register [language | ||
| data](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt) providers. | ||
| */ | ||
| static languageData: Facet<(state: EditorState, pos: number) => readonly { | ||
@@ -249,9 +1021,74 @@ [name: string]: any; | ||
| }[])[]>; | ||
| /** | ||
| Find the values for a given language data field, provided by the | ||
| the [`languageData`](https://codemirror.net/6/docs/ref/#state.EditorState^languageData) facet. | ||
| */ | ||
| languageDataAt<T>(name: string, pos: number): readonly T[]; | ||
| /** | ||
| Return a function that can categorize strings (expected to | ||
| represent a single [grapheme cluster](https://codemirror.net/6/docs/ref/#text.findClusterBreak)) | ||
| into one of: | ||
| - Word (contains an alphanumeric character or a character | ||
| explicitly listed in the local language's `"wordChars"` | ||
| language data, which should be a string) | ||
| - Space (contains only whitespace) | ||
| - Other (anything else) | ||
| */ | ||
| charCategorizer(at: number): (char: string) => CharCategory; | ||
| /** | ||
| Facet used to register change filters, which are called for each | ||
| transaction (unless explicitly | ||
| [disabled](https://codemirror.net/6/docs/ref/#state.TransactionSpec.filter)), and can suppress | ||
| part of the transaction's changes. | ||
| Such a function can return `true` to indicate that it doesn't | ||
| want to do anything, `false` to completely stop the changes in | ||
| the transaction, or a set of ranges in which changes should be | ||
| suppressed. Such ranges are represented as an array of numbers, | ||
| with each pair of two number indicating the start and end of a | ||
| range. So for example `[10, 20, 100, 110]` suppresses changes | ||
| between 10 and 20, and between 100 and 110. | ||
| */ | ||
| static changeFilter: Facet<(tr: Transaction) => boolean | readonly number[], readonly ((tr: Transaction) => boolean | readonly number[])[]>; | ||
| /** | ||
| Facet used to register a hook that gets a chance to update or | ||
| replace transaction specs before they are applied. This will | ||
| only be applied for transactions that don't have | ||
| [`filter`](https://codemirror.net/6/docs/ref/#state.TransactionSpec.filter) set to `false`. You | ||
| can either return a single (possibly the input transaction), or | ||
| an array of specs (which will be combined in the same way as the | ||
| arguments to [`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update)). | ||
| When possible, it is recommended to avoid accessing | ||
| [`Transaction.state`](https://codemirror.net/6/docs/ref/#state.Transaction.state) in a filter, | ||
| since it will force creation of a state that will then be | ||
| discarded again, if the transaction is actually filtered. | ||
| (This functionality should be used with care. Indiscriminately | ||
| modifying transaction is likely to break something or degrade | ||
| the user experience.) | ||
| */ | ||
| static transactionFilter: Facet<(tr: Transaction) => TransactionSpec | readonly TransactionSpec[], readonly ((tr: Transaction) => TransactionSpec | readonly TransactionSpec[])[]>; | ||
| /** | ||
| This is a more limited form of | ||
| [`transactionFilter`](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter), | ||
| which can only add | ||
| [annotations](https://codemirror.net/6/docs/ref/#state.TransactionSpec.annotations) and | ||
| [effects](https://codemirror.net/6/docs/ref/#state.TransactionSpec.effects). _But_, this type | ||
| of filter runs even the transaction has disabled regular | ||
| [filtering](https://codemirror.net/6/docs/ref/#state.TransactionSpec.filter), making it suitable | ||
| for effects that don't need to touch the changes or selection, | ||
| but do want to process every transaction. | ||
| Extenders run _after_ filters, when both are applied. | ||
| */ | ||
| static transactionExtender: Facet<(tr: Transaction) => Pick<TransactionSpec, "effects" | "annotations"> | null, readonly ((tr: Transaction) => Pick<TransactionSpec, "effects" | "annotations"> | null)[]>; | ||
| } | ||
| /** | ||
| Subtype of [`Command`](https://codemirror.net/6/docs/ref/#view.Command) that doesn't require access | ||
| to the actual editor view. Mostly useful to define commands that | ||
| can be run and tested outside of a browser environment. | ||
| */ | ||
| declare type StateCommand = (target: { | ||
@@ -262,2 +1099,8 @@ state: EditorState; | ||
| /** | ||
| Utility function for combining behaviors to fill in a config | ||
| object from an array of provided configs. Will, by default, error | ||
| when a field gets two values that aren't `===`-equal, but you can | ||
| provide combine functions per field to do something else. | ||
| */ | ||
| declare function combineConfig<Config>(configs: readonly Partial<Config>[], defaults: Partial<Config>, // Should hold only the optional properties of Config, but I haven't managed to express that | ||
@@ -264,0 +1107,0 @@ combine?: { |
| { | ||
| "name": "@codemirror/state", | ||
| "version": "0.18.0", | ||
| "version": "0.18.1", | ||
| "description": "Editor state data structures for the CodeMirror code editor", | ||
| "scripts": { | ||
| "test": "mocha test/test-*.js", | ||
| "prepare": "tsc -p tsconfig.local.json && rollup -c" | ||
| "prepare": "cm-buildhelper src/index.ts" | ||
| }, | ||
@@ -32,5 +32,3 @@ "keywords": [ | ||
| "devDependencies": { | ||
| "rollup": "^2.35.1", | ||
| "rollup-plugin-dts": "^2.0.1", | ||
| "typescript": "^4.1.3", | ||
| "@codemirror/buildhelper": "^0.1.0", | ||
| "@types/mocha": "^5.2.0", | ||
@@ -37,0 +35,0 @@ "ist": "^1.1.6", |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Dev dependency count
- decreased by-33.33%
4
- Lines of code
- increased by36.78%
5344
Worsened metrics
- Total package byte prevSize
- decreased by-34.75%
203516
- Number of package files
- decreased by-20%
8
No dependency changes