@folijs/view 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/view.d.ts ADDED
@@ -0,0 +1,261 @@
1
+ import { type Editor } from "@folijs/core";
2
+ interface DomPoint {
3
+ node: Node;
4
+ offset: number;
5
+ }
6
+ export interface EditorViewOptions {
7
+ /** Whether the user can change the document (default true). Code can always change it. */
8
+ editable?: boolean;
9
+ /** Shown while the document is one empty block (default: none). */
10
+ placeholder?: string;
11
+ }
12
+ /**
13
+ * The editable view of an `Editor` from `@folijs/core`: renders its state into one
14
+ * `contenteditable` host and turns DOM input into core commands. The model is the source of
15
+ * truth; the DOM is rebuilt from it (unchanged blocks are reused by node identity).
16
+ *
17
+ * The browser edits the DOM itself only during composition (IME, dead keys) and for changes the
18
+ * view cannot prevent (Android keyboards, extensions). A MutationObserver records those; the view
19
+ * then reads the changed text back into a transaction (`readBack`) and re-renders.
20
+ *
21
+ * Blocks are the leaf blocks of the document at any depth (paragraphs, headings, rules); the
22
+ * containers around them (lists, list items) are rebuilt on each page around the blocks it holds
23
+ * (ADR-0004).
24
+ */
25
+ export declare class EditorView {
26
+ readonly host: HTMLElement;
27
+ readonly editor: Editor;
28
+ private state;
29
+ private blocks;
30
+ /** Position before each block, parallel to `blocks`. */
31
+ private starts;
32
+ /** The containers around each block, outermost first, parallel to `blocks`. */
33
+ private chains;
34
+ /** The index of each block in `blocks`. */
35
+ private indexOf;
36
+ /** The container types around each block at its last render (a change means re-measuring). */
37
+ private chainKeys;
38
+ /** The element that shows a node selection, if any. */
39
+ private selectedDom;
40
+ /** The page of each fragment of each block. */
41
+ private fragmentPages;
42
+ /** The block each fragment element belongs to. */
43
+ private owner;
44
+ /** The page elements, in order; the host's only children. */
45
+ private pages;
46
+ private pageStyle;
47
+ /** Marks the host for this view's print rules (`printStyles`). */
48
+ private readonly id;
49
+ /**
50
+ * This view's print rules: in the document's head (`@page` only applies there) and, for a host
51
+ * in a shadow root, there too (page rules do not cross into it).
52
+ */
53
+ private printStyles;
54
+ private destroyed;
55
+ /** Set by a render during a composition, which places blocks but does not flow them. */
56
+ private unflowed;
57
+ /**
58
+ * Measurements by model node: a node's rendered height, margins and lines only depend on
59
+ * its content (unchanged node, same identity), the page width and the CSS. Cleared when the
60
+ * page settings or the fonts change; single entries go stale when a block's size changes
61
+ * without an edit (`ResizeObserver`: CSS, fonts, a container).
62
+ */
63
+ private measures;
64
+ private readonly stale;
65
+ /**
66
+ * Set when a block resized without an edit: the CSS or a font changed, and may have rewrapped
67
+ * other blocks without changing their height. The next render drops every cached line list
68
+ * (heights stay; lines are measured again only for blocks that cross a page end).
69
+ */
70
+ private linesStale;
71
+ /** The last flow and the nodes it was made for, for the next incremental one. */
72
+ private flowed;
73
+ private readonly resizeObserver;
74
+ private readonly observed;
75
+ private relayoutPending;
76
+ private composing;
77
+ /** Set by Ctrl/Cmd+Shift+V for the paste event it triggers. */
78
+ private plainPaste;
79
+ /** Blocks whose DOM the browser changed: the next render rebuilds them. */
80
+ private readonly dirty;
81
+ /** DOM mutations not yet read back (kept while a composition is running). */
82
+ private pending;
83
+ private readonly observer;
84
+ private readonly unsubscribe;
85
+ private editable;
86
+ private placeholder;
87
+ /** The block that shows the placeholder, if any. */
88
+ private placeholderDom;
89
+ /** Set by a mousedown that focuses the host: the click places the caret, not the view. */
90
+ private pointerFocus;
91
+ /** Whether the view added the host's tabindex (a read-only host must stay focusable). */
92
+ private readonly addedTabIndex;
93
+ constructor(host: HTMLElement, editor: Editor, options?: EditorViewOptions);
94
+ destroy(): void;
95
+ /** Focuses the host, shows the model selection in it and scrolls it into view. */
96
+ focus(): void;
97
+ /** Changes the given options; the others keep their value. */
98
+ setOptions(options: EditorViewOptions): void;
99
+ /**
100
+ * Marks the only block while the document is one empty textblock; CSS shows the text. Hidden
101
+ * during a composition, whose text the model does not have yet.
102
+ */
103
+ private showPlaceholder;
104
+ private update;
105
+ /**
106
+ * Scrolls the selection head into view. Browsers do it for their own edits and caret moves,
107
+ * not when the view changes the DOM and sets the selection (typing, Enter, undo, paste).
108
+ */
109
+ private scrollToSelection;
110
+ /**
111
+ * Renders the document into pages, reusing the DOM of blocks whose model node is unchanged.
112
+ * Blocks are first placed where they were (a new block joins the page of the block before
113
+ * it), then measured and flowed: a block that does not fit is split at a line boundary into
114
+ * fragments on consecutive pages. During a composition nothing moves, since moving or
115
+ * re-splitting the DOM the browser is composing in would break the IME.
116
+ *
117
+ * Measurements are cached by node and the flow restarts at the first changed block (5.4).
118
+ */
119
+ private render;
120
+ /**
121
+ * Puts each fragment of each block into its page (pages are non-decreasing in document
122
+ * order), inside the elements of the block's containers (lists, list items), creating and
123
+ * removing pages as needed. A page reuses the container elements already at the same place
124
+ * (same tag, in order), so an edit inside a list moves no DOM. Anything else in the host, a
125
+ * page or a container (stray DOM) is removed.
126
+ */
127
+ private place;
128
+ private createPage;
129
+ /** Page size and margins from the document settings, applied to every page when they change. */
130
+ private applyGeometry;
131
+ /** Forgets every measurement: the next flow measures the whole document again. */
132
+ private invalidateLayout;
133
+ /** Re-flows the pages once web fonts have loaded: line heights and wrapping change. */
134
+ private onFontsLoaded;
135
+ /** Observes the size of every rendered block element (and only those). */
136
+ private observeSizes;
137
+ /**
138
+ * A block whose height no longer matches its measurement changed without an edit (CSS, a web
139
+ * font, the content width): measure it again and re-flow, once per frame.
140
+ */
141
+ private onResize;
142
+ /** Re-flows in the next animation frame (several requests in one frame make one pass). */
143
+ private scheduleRelayout;
144
+ /** The block element (a fragment of a rendered block) that contains `node`, or null. */
145
+ private blockElement;
146
+ /** Whether `node` holds blocks rather than content: the host, a page or a container. */
147
+ private holdsBlocks;
148
+ /** Index of the first block that starts at or after `pos` (the block count if none). */
149
+ private blockFrom;
150
+ /** Model position of a DOM point inside the host, or null if it is outside. */
151
+ posFromDOM(node: Node, offset: number): number | null;
152
+ /** DOM point for a model position. At a mark boundary the caret stays in the text before it. */
153
+ domFromPos(pos: number): DomPoint;
154
+ /** The live DOM selection as a model selection, or null if it is not inside the host. */
155
+ private readSelection;
156
+ /** The rendered block a node selection selects, if it selects one. */
157
+ private selectedBlock;
158
+ /** Marks the element of a node-selected block, for styling (the DOM selection is around it). */
159
+ private showSelectedNode;
160
+ /**
161
+ * Brings the model selection up to date with the DOM. `selectionchange` is asynchronous, so
162
+ * every input handler calls this first instead of trusting the last event.
163
+ */
164
+ private syncSelection;
165
+ /**
166
+ * Whether a selection read from the DOM already shows the model selection. An AllSelection is
167
+ * shown as the text range between its snapped ends, so reading it back must not replace it.
168
+ */
169
+ private shows;
170
+ private hasFocus;
171
+ /** Writes the model selection to the DOM unless the DOM already shows it (keeps native affinity). */
172
+ private writeSelection;
173
+ private run;
174
+ /**
175
+ * Every change from user input goes through here. Read-only mode drops document changes and
176
+ * newly stored marks (Mod+B on a caret); selection changes, and clearing stored marks, still
177
+ * apply. Code can always change the document through the editor.
178
+ */
179
+ private dispatch;
180
+ /** Selects the event's target range when the browser gives a non-empty one (spellcheck, deletes). */
181
+ private selectTargetRange;
182
+ private onBeforeInput;
183
+ /** Runs the first command bound to `name` that applies, through the view's dispatch. */
184
+ private runKey;
185
+ /**
186
+ * Triple-click selects the clicked block's content. Chromium and WebKit natively extend the
187
+ * selection to the start of the next block, so typing over it would merge the two blocks.
188
+ */
189
+ private onMouseDown;
190
+ /**
191
+ * A click on a link in the document does not navigate (it places the caret, also in read-only
192
+ * mode); Ctrl+click (Cmd+click on Apple platforms) opens it in a new tab, without `opener`.
193
+ */
194
+ private onClick;
195
+ /** The href of the link an `<a>` shows, read from the model (the DOM is never the truth). */
196
+ private linkHref;
197
+ private onKeyDown;
198
+ /**
199
+ * Whether the caret is on the first (`dir` -1) or last (1) line of its textblock, in the
200
+ * block's first or last fragment (a block split across pages has several).
201
+ */
202
+ private caretOnEdgeLine;
203
+ /**
204
+ * Caret affinity at a page break. The end of one fragment and the start of the next are two
205
+ * DOM caret stops for one model position, so a native Left/Right (or word move) there would
206
+ * seem to do nothing. Step over the edge first, then let the browser make the move.
207
+ *
208
+ * shortcut: left-to-right only (ArrowRight is forward); bidi text needs visual order here and in the line measurement.
209
+ */
210
+ private crossFragmentEdge;
211
+ /** Safety net: a DOM change that was not prevented is read back into the model. */
212
+ private onInput;
213
+ private onCompositionStart;
214
+ private onCompositionEnd;
215
+ /**
216
+ * Focus from the keyboard or from code shows the model selection: once the page selection has
217
+ * moved elsewhere, browsers put the caret at the start of the host instead. A DOM selection
218
+ * that already shows the model selection (the window or tab regaining focus) is left alone,
219
+ * and so is the scroll position.
220
+ */
221
+ private onFocus;
222
+ /** Some browsers drop compositionend when focus leaves mid-composition; never stay stuck in it. */
223
+ private onBlur;
224
+ private onMutations;
225
+ /** Reads back every DOM change recorded so far. */
226
+ private flush;
227
+ /**
228
+ * Turns DOM changes into a transaction: diffs the DOM text with the model text (blocks joined
229
+ * by a separator, hard breaks as one character) and replaces the minimal changed range. The
230
+ * DOM caret only breaks ties, so typing "a" after "a" lands where the browser put it. Blocks
231
+ * whose DOM was touched are re-rendered even if their text is unchanged.
232
+ *
233
+ * shortcut: diffs the whole document text (O(document) per composition); limit it to the
234
+ * touched blocks if it shows in profiles.
235
+ */
236
+ private readBack;
237
+ /** Rebuilds every block that is not reused and puts the selection back. */
238
+ private rerender;
239
+ /** Copy writes the model's content (plain text, HTML, Foli JSON), never the browser's DOM. */
240
+ private onCopy;
241
+ private onCut;
242
+ private onPaste;
243
+ /**
244
+ * Replaces the selection with clipboard content (Foli JSON, else HTML, else plain text). The
245
+ * paste starts a new undo step (typing right after it joins that step). Closed content (whole
246
+ * blocks) goes into an empty textblock whole, so a pasted heading stays a heading; open
247
+ * content, and anything pasted into a non-empty block, joins the text around the selection,
248
+ * so the target block keeps its type. Plain text that is one URL becomes a link (`autolink`,
249
+ * not for paste as plain text): over selected text inside one block, that text is linked;
250
+ * otherwise the URL is inserted as linked text. Returns whether anything was inserted.
251
+ */
252
+ paste(data: Pick<DataTransfer, "getData">, autolink?: boolean): boolean;
253
+ private onSelectionChange;
254
+ }
255
+ /**
256
+ * Normalizes a key event to a keymap name: modifiers in the order `Mod-Ctrl-Meta-Alt-Shift-`,
257
+ * then the key (single characters lower-cased). `Mod` is Cmd on Apple platforms, Ctrl elsewhere.
258
+ */
259
+ export declare function keyName(event: KeyboardEvent): string;
260
+ export {};
261
+ //# sourceMappingURL=view.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"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"}