extension-positioner

package @remirror/extension-positioner

class Positioner

This is the positioner. It exists to report the position of things in the editor. Typically you will use it to get the position of the cursor.

But you can be more ambitious and get the position all the active nodes of a certain type. Or all visible nodes of a certain type in the editor, updated as it scrolls.

The positions returned have a rect which is the viewport position.

There are also the top, left, right, bottom which represent the absolute positioned rectangle of the position in questions. For a cursor position left and right are probably the same.

Signature:

export declare class Positioner<Data = any> 

property addListener

Add a listener to the positioner events.

Signature:

readonly addListener: <Key extends keyof PositionerEvents<Data>>(event: Key, cb: PositionerEvents<Data>[Key]) => Unsubscribe;

property basePositioner

Signature:

get basePositioner(): BasePositioner<Data>;

property EMPTY

An empty return value for the positioner.

Signature:

static EMPTY: never[];

property events

Signature:

readonly events: PositionerUpdateEvent[];

property hasChanged

Signature:

readonly hasChanged: (props: BasePositionerProps) => boolean;

property recentUpdate

Store the props for the most recent update. This is used by React to reapply the most recent props to the new positioner when the positioner is recreated within a component.

Signature:

recentUpdate?: GetActiveProps;

method active

Clones the positioner while updating the active value. This is designed for usage in frameworks like react.

Signature:

active(isActive: boolean | ((data: Data) => boolean)): Positioner<Data>;

Parameters:

Parameter	Type	Description
isActive	boolean | ((data: Data) => boolean)

Returns:

Positioner<Data>

method clone

Create a new Positioner with the provided props.

Signature:

clone(props?: PositionerCloneProps<Data>): Positioner<Data>;

Parameters:

Parameter	Type	Description
props	PositionerCloneProps<Data>	(Optional)

Returns:

Positioner<Data>

method create

Create a positioner.

Signature:

static create<Data>(props: BasePositioner<Data>): Positioner<Data>;

Parameters:

Parameter	Type	Description
props	BasePositioner<Data>

Returns:

Positioner<Data>

method fromPositioner

Create a positioner from an existing positioner.

This is useful when you want to modify parts of the positioner.

Signature:

static fromPositioner<Data>(positioner: Positioner, base: Partial<BasePositioner<Data>>): Positioner<Data>;

Parameters:

Parameter	Type	Description
positioner	Positioner
base	Partial<BasePositioner<Data>>

Returns:

Positioner<Data>

method getID

Get the id for the active data. Defaults to the index of the data item.

Signature:

getID(data: Data, index: number): string;

Parameters:

Parameter	Type	Description
data	Data
index	number

Returns:

string

method onActiveChanged

Get the active element setters.

Signature:

onActiveChanged(props: GetActiveProps): void;

Parameters:

Parameter	Type	Description
props	GetActiveProps

Returns:

void

class PositionerExtension

This is the positioner extension which is used to track the positions of different parts of your editor.

For example, you can track the cursor or all visible paragraph nodes.

Signature:

export declare class PositionerExtension extends PlainExtension<PositionerOptions> 

Extends: PlainExtension<PositionerOptions>

(Some inherited members may not be shown because they are not represented in the documentation.)

property name

Signature:

get name(): "positioner";

property onAddCustomHandler

Signature:

protected onAddCustomHandler: AddCustomHandler<PositionerOptions>;

method createAttributes

Signature:

createAttributes(): ProsemirrorAttributes;

Returns:

ProsemirrorAttributes

method createDecorations

Create a placeholder decoration which is never removed from the document.

Signature:

createDecorations(state: EditorState): DecorationSet;

Parameters:

Parameter	Type	Description
state	EditorState

Returns:

DecorationSet

method createEventHandlers

Signature:

createEventHandlers(): CreateEventHandlers;

Returns:

CreateEventHandlers

method forceUpdatePositioners

Trigger an update of positioners manually. This can be useful to update positioners when the view is updated in a way that doesn't trigger a ProseMirror state change. For instance when an image URL is loaded and the document is reflowed.

Signature:

forceUpdatePositioners(key?: string): CommandFunction;

Parameters:

Parameter	Type	Description
key	string	(Optional) Allows filtering a specific type of positioner to update. Defaults to all.

Returns:

CommandFunction

method getPositionerWidget

Get the html element which contains all the positioner elements and components.

Signature:

getPositionerWidget(): Helper<HTMLElement>;

Returns:

Helper<HTMLElement>

method init

Signature:

protected init(): void;

Returns:

void

method onStateUpdate

Signature:

onStateUpdate(update: StateUpdateLifecycleProps): void;

Parameters:

Parameter	Type	Description
update	StateUpdateLifecycleProps

Returns:

void

function createMarkPositioner()

Create a positioner for the currently selected mark

Signature:

export declare function createMarkPositioner(props: MarkPositionerProps): Positioner<CreateMarkPositionerData>;

Parameters:

Parameter	Type	Description
props	MarkPositionerProps

Returns:

Positioner<CreateMarkPositionerData>

function getPositioner()

This is a helper method for getting the positioner. The props can either be a named positioner or a positioner that you've created for the purpose.

Signature:

export declare function getPositioner(positioner: PositionerParam): Positioner;

Parameters:

Parameter	Type	Description
positioner	PositionerParam

Returns:

Positioner

function hasStateChanged()

Checks the transaction for changes or compares the state with the previous state.

Return true when a change is detected in the document or the selection.

Signature:

export declare function hasStateChanged(props: HasChangedProps): boolean;

Parameters:

Parameter	Type	Description
props	HasChangedProps

Returns:

boolean

function isPositionerUpdateTransaction()

Checks if the given transaction force updates positioners.

Signature:

export declare function isPositionerUpdateTransaction(tr: Transaction, key?: string): boolean;

Parameters:

Parameter	Type	Description
tr	Transaction	the Transaction to check
key	string	(Optional) filter for a specific key. Defaults to all.

Returns:

boolean

function isPositionVisible()

Checks that the rect is visible within the provided element.

This is specific for the remirror editor.

Signature:

export declare function isPositionVisible(rect: DOMRect, element: Element, options?: IsPositionVisibleOptions): boolean;

Parameters:

Parameter	Type	Description
rect	DOMRect
element	Element
options	IsPositionVisibleOptions	(Optional)

Returns:

boolean

variable alwaysPositioner

Always render a position regardless of selection.

Signature:

alwaysPositioner: Positioner<{
    from: Coords;
    to: Coords;
}>

variable blockNodePositioner

Creates a positioner for the current block node.

It spans the full width and height of the block.

Signature:

blockNodePositioner: Positioner<FindProsemirrorNodeResult>

variable cursorPositioner

This can be used to position a menu that is inline with the first character of the selection. This is useful for suggestions since they should typically appear while typing without a multi character selection.

Signature:

cursorPositioner: Positioner<{
    from: Coords;
    to: Coords;
}>

Remarks:

The menu will center itself within the selection.

• right should be used to absolutely position away from the right hand edge of the screen. - left should be used to absolutely position away from the left hand edge of the screen. - bottom absolutely positions the element above the text selection. - top absolutely positions the element below the text selection

variable defaultAbsolutePosition

Signature:

defaultAbsolutePosition: PositionerPosition

variable editorPositioner

Creates a positioner for the visible portion editor.

E.g. The "viewport" of the editor inside any scrollable area.

Signature:

editorPositioner: Positioner<boolean>

variable emptyBlockNodeEndPositioner

Returns the position as a single pixel width for the end of the current block node.

Signature:

emptyBlockNodeEndPositioner: Positioner<FindProsemirrorNodeResult>

variable emptyBlockNodePositioner

Returns the block node position only when it is empty and the selection is empty.

Signature:

emptyBlockNodePositioner: Positioner<FindProsemirrorNodeResult>

variable emptyBlockNodeStartPositioner

Returns the position as a single pixel width for the start of the block node as a position

Signature:

emptyBlockNodeStartPositioner: Positioner<FindProsemirrorNodeResult>

variable nearestWordPositioner

Creates a position which captures the current active word. Nothing is returned if no word is active.

This is only active when the selection is empty (cursor selection)

Signature:

nearestWordPositioner: Positioner<{
    from: Coords;
    to: Coords;
}>

Remarks:

Creates a rect that wraps the nearest word.

variable POSITIONER_UPDATE_ALL

Signature:

POSITIONER_UPDATE_ALL = "__all_positioners__"

variable POSITIONER_UPDATE_KEY

Signature:

POSITIONER_UPDATE_KEY = "positionerUpdate"

variable POSITIONER_WIDGET_KEY

Signature:

POSITIONER_WIDGET_KEY = "remirror-positioner-widget"

variable positioners

Signature:

positioners: {
    selection: Positioner<{
        from: Coords;
        to: Coords;
    }>;
    cursor: Positioner<{
        from: Coords;
        to: Coords;
    }>;
    always: Positioner<{
        from: Coords;
        to: Coords;
    }>;
    block: Positioner<FindProsemirrorNodeResult>;
    emptyBlock: Positioner<FindProsemirrorNodeResult>;
    emptyBlockStart: Positioner<FindProsemirrorNodeResult>;
    emptyBlockEnd: Positioner<FindProsemirrorNodeResult>;
    nearestWord: Positioner<{
        from: Coords;
        to: Coords;
    }>;
    editor: Positioner<boolean>;
}

variable selectionPositioner

Create a position that fully capture the selected text. When the selection spans multiple lines, the position is created as a box that fully captures the start cursor and end cursor.

Signature:

selectionPositioner: Positioner<{
    from: Coords;
    to: Coords;
}>

interface BasePositioner

Signature:

export interface BasePositioner<Data> 

property events

An array of update listeners to determines when the positioner will update it's position.

• state - updates when the prosemirror state is updated - default. - scroll - updates when the editor is scrolled (debounced)

Signature:

events?: PositionerUpdateEvent[];

property getActive

Get the active items that will be passed into the getPosition method.

Signature:

getActive: (props: GetActiveProps) => Data[];

property getID

Get a unique id for the data returned from getActive.

If left undefined, it defaults to use the index.

Signature:

getID?: (data: Data, index: number) => string;

property getPosition

Calculate and return an array of VirtualPosition's which represent the virtual element the positioner represents.

Signature:

getPosition: (props: GetPositionProps<Data>) => PositionerPosition;

property hasChanged

Determines whether anything has changed and whether to continue with a recalculation. By default this is only true when the document has or selection has changed.

Signature:

hasChanged: (props: BasePositionerProps) => boolean;

Remarks:

Sometimes it is useful to recalculate the positioner on every state update. In this case you can set this method to always return true.

const positioner: Positioner = {
  hasStateChanged: () => true
};

interface BasePositionerProps

Signature:

export interface BasePositionerProps extends Omit<StateUpdateLifecycleProps, 'previousState'> 

Extends: Omit<StateUpdateLifecycleProps, 'previousState'>

(Some inherited members may not be shown because they are not represented in the documentation.)

property contextmenu

The contextmenu event information. This is only present when the update was triggered by a contextmenu event.

Signature:

contextmenu?: Except<MouseEventHandlerState, 'view'>;

property event

The event that triggered this update.

Signature:

event: PositionerUpdateEvent;

property helpers

Signature:

helpers: Record<string, AnyFunction>;

property hover

The hover event information. This is only present when the update was triggered by a hover event.

Signature:

hover?: Except<HoverEventHandlerState, 'view'>;

property previousState

Signature:

previousState: undefined | EditorState;

property scroll

The scroll event information.

Signature:

scroll?: {
        scrollTop: number;
    };

interface ElementsAddedProps

Signature:

export interface ElementsAddedProps 

property element

Signature:

element: HTMLElement;

property id

Signature:

id: string;

property position

Signature:

position: PositionerPosition;

interface GetActiveProps

Signature:

export interface GetActiveProps extends EditorViewProps, BasePositionerProps 

Extends: EditorViewProps, BasePositionerProps

(Some inherited members may not be shown because they are not represented in the documentation.)

property contextmenu

The contextmenu event information. This is only present when the update was triggered by a contextmenu event.

Signature:

contextmenu?: Except<MouseEventHandlerState, 'view'>;

property event

The event that triggered this update.

Signature:

event: PositionerUpdateEvent;

property helpers

Signature:

helpers: Record<string, AnyFunction>;

property hover

The hover event information. This is only present when the update was triggered by a hover event.

Signature:

hover?: Except<HoverEventHandlerState, 'view'>;

property previousState

Signature:

previousState: undefined | EditorState;

property scroll

The scroll event information.

Signature:

scroll?: {
        scrollTop: number;
    };

property view

An instance of the Prosemirror editor view.

Signature:

view: EditorView;

interface GetPositionProps

Signature:

export interface GetPositionProps<Data> extends EditorViewProps, BasePositionerProps 

Extends: EditorViewProps, BasePositionerProps

(Some inherited members may not be shown because they are not represented in the documentation.)

property contextmenu

The contextmenu event information. This is only present when the update was triggered by a contextmenu event.

Signature:

contextmenu?: Except<MouseEventHandlerState, 'view'>;

property data

The data that can be transformed into a position.

Signature:

data: Data;

property element

The reference element being used by the positioner to determine positioning.

Signature:

element: HTMLElement;

property event

The event that triggered this update.

Signature:

event: PositionerUpdateEvent;

property helpers

Signature:

helpers: Record<string, AnyFunction>;

property hover

The hover event information. This is only present when the update was triggered by a hover event.

Signature:

hover?: Except<HoverEventHandlerState, 'view'>;

property previousState

Signature:

previousState: undefined | EditorState;

property scroll

The scroll event information.

Signature:

scroll?: {
        scrollTop: number;
    };

property view

An instance of the Prosemirror editor view.

Signature:

view: EditorView;

interface MarkPositionerProps

Signature:

export interface MarkPositionerProps 

property all

When true will find all marks of the provided type in the doc.

Signature:

all?: boolean;

property onlyVisible

When true will only be active for the visible positions.

Signature:

onlyVisible?: boolean;

property type

The type of mark to look for.

Signature:

type: MarkType | string;

interface PositionerHandler

Signature:

export interface PositionerHandler 

property onChange

Method to call when there is a change in the position.

Signature:

onChange: PositionerChangeHandlerMethod;

property positioner

The positioner to use for calculating the relative position.

Signature:

positioner: Positioner;

interface PositionerOptions

Signature:

export interface PositionerOptions 

property positioner

An object specifying the positioner and the change handler for responding to changes in the positioner output. This is a custom handler and should be amended with addCustomHandler.

Signature:

positioner?: CustomHandler<Positioner>;

property scrollDebounce

The ms to debounce scroll events. Scroll events affect the visibility of the rendered positioners. By default they are enabled for all positioners.

Signature:

scrollDebounce?: Static<number>;

interface PositionerPosition

The absolutely positioned coordinates relative to the editor element. With these coordinates you can perfectly simulate a position within the text editor and render it as you decide.

Signature:

export interface PositionerPosition extends Rect 

Extends: Rect

property height

The height of the captured position.

Signature:

height: number;

property rect

The position relative to the document viewport. This can be used with position: fixed when that is a better fit for your application.

Signature:

rect: DOMRect;

property visible

True when any part of the captured position is visible within the dom view.

Signature:

visible: boolean;

property width

The width of the captured position.

Signature:

width: number;

property x

Pixel distance from left of the reference frame. Alias of left.

Signature:

x: number;

property y

Pixel distance from top of the reference frame. Alias of top for css.

Signature:

y: number;

interface Rect

Signature:

export interface Rect 

property height

The height of the captured position.

Signature:

height: number;

property width

The width of the captured position.

Signature:

width: number;

property x

Pixel distance from left of the reference frame. Alias of left.

Signature:

x: number;

property y

Pixel distance from top of the reference frame. Alias of top for css.

Signature:

y: number;

interface SetActiveElement

Signature:

export interface SetActiveElement<Data = any> 

property data

Signature:

data: Data;

property id

The unique ide for the active element.

Signature:

id: string;

property setElement

Set the html element for the active position.

Signature:

setElement: (element: HTMLElement) => void;

interface VisibleProps

Signature:

export interface VisibleProps 

property visible

Signature:

visible: boolean;

type CallbackPositioner

Signature:

export type CallbackPositioner = () => Positioner;

References: Positioner

type PositionerChangeHandlerMethod

This type is used for setting elements which are associated with the relevant positioner. Once teh

Signature:

export type PositionerChangeHandlerMethod = (elementSetters: SetActiveElement[]) => void;

References: SetActiveElement

type PositionerParam

Signature:

export type PositionerParam = StringPositioner | Positioner | CallbackPositioner;

References: StringPositioner, Positioner, CallbackPositioner

type PositionerUpdateEvent

The events that can trigger a positioner update.

Signature:

export type PositionerUpdateEvent = 'scroll' | 'state' | 'hover' | 'contextmenu';

type StringPositioner

Signature:

export type StringPositioner = keyof typeof positioners;

References: positioners