@monster-orange/den-ui 0.7.1 → 0.7.5

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.
@@ -0,0 +1,187 @@
1
+ /**
2
+ * The kit's Markdown editor (0.7.5): CodeMirror 6 on the Markdown text, the
3
+ * live preview drawn in place, IME-safe, loaded lazily. Link
4
+ * markdown-editor.css after tokens.css.
5
+ */
6
+
7
+ /** "full": a form field with a toolbar; Enter is a new line, ⌘/Ctrl+Enter submits. "lite": a chat box, no toolbar; Enter sends, Shift+Enter is a new line. */
8
+ export type MarkdownMode = "full" | "lite";
9
+ export type InlineFormat = "bold" | "italic" | "code" | "strike";
10
+ export type BlockFormat = "heading" | "bullet" | "ordered" | "quote";
11
+ export type MarkdownFormat = InlineFormat | BlockFormat | "link";
12
+
13
+ export interface MarkdownEditorOptions {
14
+ /** The text it opens with: the Markdown source, kept byte for byte. */
15
+ value?: string;
16
+ /** Every change the person makes, as the whole Markdown source. Never called for setValue. */
17
+ onChange?: (value: string) => void;
18
+ /** Default "full". */
19
+ mode?: MarkdownMode;
20
+ /** The editing surface's id (the stand-in textarea has it first). Default: one made up. */
21
+ id?: string;
22
+ /** The editor's accessible name (aria-label). Give this or labelledBy. */
23
+ label?: string;
24
+ /** The id of the element that names it (aria-labelledby). */
25
+ labelledBy?: string;
26
+ /** The ids of the elements that describe it: help, an error (aria-describedby). */
27
+ describedBy?: string;
28
+ placeholder?: string;
29
+ /** full: ⌘/Ctrl+Enter; lite: Enter. Never while an IME is composing. */
30
+ onSubmit?: () => void;
31
+ /** Escape inside the editor; it stops there (a dialog around it stays open). */
32
+ onEscape?: () => void;
33
+ /** Focus left the field, the toolbar included. */
34
+ onBlur?: () => void;
35
+ disabled?: boolean;
36
+ /** No toolbar, no edits; the text can still be selected and copied. */
37
+ readOnly?: boolean;
38
+ /** Counts the Markdown SOURCE (what is stored), as a textarea's maxLength does. An open IME composition is never cut. */
39
+ maxLength?: number;
40
+ required?: boolean;
41
+ /** Marks it invalid (aria-invalid, the danger border) when its message is shown elsewhere. */
42
+ invalid?: boolean;
43
+ /** The text's language (the lang attribute), for spelling and line breaking. */
44
+ lang?: string;
45
+ /** The language of the toolbar's words: en, es or ja. Default: <html lang>, else en. */
46
+ uiLang?: string;
47
+ /** full: the editing area's minimum height in text rows (default 3). */
48
+ rows?: number;
49
+ /** full: false hides the toolbar (the shortcuts still work). */
50
+ toolbar?: boolean;
51
+ /** No link button (a field whose text may not hold a link). */
52
+ noLinks?: boolean;
53
+ autoFocus?: boolean;
54
+ /** Where the caret goes when the editor arrives (default: where it was in the stand-in, else nowhere). */
55
+ initialCaret?: number;
56
+ /** The page's CSP nonce: CodeMirror writes its base styles into a <style>. */
57
+ nonce?: string;
58
+ /** Classes added to the field's box (.md-field). */
59
+ className?: string;
60
+ }
61
+
62
+ /** What `update` may change after mounting. */
63
+ export type MarkdownEditorUpdate = Partial<
64
+ Omit<MarkdownEditorOptions, "value" | "mode" | "id" | "nonce" | "rows">
65
+ >;
66
+
67
+ export interface MarkdownEditor {
68
+ /** Resolves when CodeMirror has taken over from the stand-in; rejects when it could not load (the stand-in stays and works). */
69
+ readonly ready: Promise<void>;
70
+ /** The Markdown source now. */
71
+ getValue(): string;
72
+ /** A value from outside (a send cleared it, a server answered): onChange is not called, and it is the new unsaved-changes baseline. */
73
+ setValue(value: string): void;
74
+ focus(): void;
75
+ /** What a toolbar button or shortcut does, on the selection. */
76
+ run(format: MarkdownFormat): void;
77
+ /** Put a block where the caret is, on lines of its own. */
78
+ insertBlock(block: string): void;
79
+ /** Put a link where the caret is, the selected words (else `label`) as its words. */
80
+ insertLinkTo(label: string, url: string): void;
81
+ /** Replace the last `count` characters with `text`, the caret after it. */
82
+ replaceEnd(count: number, text: string): void;
83
+ /** Change options: names, state, callbacks, the toolbar. */
84
+ update(options: MarkdownEditorUpdate): void;
85
+ /** Takes the editor and its box away. */
86
+ destroy(): void;
87
+ }
88
+
89
+ /**
90
+ * Mounts an editor in `el`. A plain textarea takes the typing until
91
+ * CodeMirror arrives (one dynamic import, its own chunk in a bundle); then
92
+ * the editor goes on from its text, focus, caret and selection. The
93
+ * content element carries `data-md-dirty` while it holds unsaved text.
94
+ */
95
+ export declare function mountMarkdownEditor(
96
+ el: Element,
97
+ options?: MarkdownEditorOptions,
98
+ ): MarkdownEditor;
99
+
100
+ /** Loads CodeMirror ahead of the first editor (once; shared). */
101
+ export declare function loadMarkdownEditor(): Promise<void>;
102
+
103
+ // The pure parts, for a product's own tests or a server.
104
+
105
+ export interface KeyLike {
106
+ key: string;
107
+ shiftKey: boolean;
108
+ altKey?: boolean;
109
+ ctrlKey?: boolean;
110
+ metaKey?: boolean;
111
+ isComposing?: boolean;
112
+ keyCode?: number;
113
+ }
114
+ /** True while the key belongs to an IME composition (isComposing, or keyCode 229). */
115
+ export declare function composingKey(
116
+ e: Pick<KeyLike, "isComposing" | "keyCode">,
117
+ ): boolean;
118
+ /** Within this long after compositionend, an Enter is the composition's (Safari): 100 ms. */
119
+ export declare const COMPOSITION_GRACE_MS: number;
120
+ /** What Enter does in a mode; "ime" while composing; null for another key. */
121
+ export declare function enterAction(
122
+ e: KeyLike,
123
+ mode: MarkdownMode,
124
+ composing?: boolean,
125
+ ): "submit" | "newline" | "ime" | null;
126
+
127
+ /** A text edit: changes in the old text's positions, the selection in the new. */
128
+ export interface MarkdownEdit {
129
+ changes: Array<{ from: number; to: number; insert: string }>;
130
+ anchor: number;
131
+ head: number;
132
+ }
133
+ export declare function toggleInline(
134
+ doc: string,
135
+ from: number,
136
+ to: number,
137
+ format: InlineFormat,
138
+ ): MarkdownEdit;
139
+ export declare function insertLink(
140
+ doc: string,
141
+ from: number,
142
+ to: number,
143
+ placeholder?: string,
144
+ ): MarkdownEdit;
145
+ export declare function toggleBlock(
146
+ doc: string,
147
+ from: number,
148
+ to: number,
149
+ format: BlockFormat,
150
+ ): MarkdownEdit;
151
+ export declare function continueBlock(
152
+ doc: string,
153
+ pos: number,
154
+ ): MarkdownEdit | null;
155
+ export declare function insertBlock(
156
+ doc: string,
157
+ from: number,
158
+ to: number,
159
+ block: string,
160
+ ): MarkdownEdit;
161
+ export declare function insertLinkTo(
162
+ doc: string,
163
+ from: number,
164
+ to: number,
165
+ label: string,
166
+ url: string,
167
+ ): MarkdownEdit;
168
+ export declare function applyEdit(doc: string, edit: MarkdownEdit): string;
169
+
170
+ /** One drawing instruction of the live preview. */
171
+ export type LiveRange =
172
+ | { kind: "hide"; from: number; to: number }
173
+ | { kind: "mark"; from: number; to: number; cls: string }
174
+ | { kind: "line"; from: number; cls: string }
175
+ | { kind: "bullet"; from: number; to: number };
176
+ /** A Lezer Markdown parser (from markdownParser). */
177
+ export interface MarkdownParser {
178
+ parse(text: string): unknown;
179
+ }
180
+ /** The preview's parser, made from the @lezer/markdown module given. */
181
+ export declare function markdownParser(md: unknown): MarkdownParser;
182
+ /** Every drawing instruction for `text`, given the selections whose lines are being edited. */
183
+ export declare function livePreview(
184
+ text: string,
185
+ selection: ReadonlyArray<readonly [number, number]>,
186
+ parser: MarkdownParser,
187
+ ): LiveRange[];