@weasel-js/text-tools 0.0.0-stage → 1.19.1
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/LICENSE +21 -0
- package/README.md +37 -2
- package/dist/index.d.ts +578 -0
- package/dist/index.js +1137 -0
- package/dist/index.js.map +1 -0
- package/package.json +69 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 orochi235
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,38 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @weasel-js/text-tools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Text for a weasel canvas: the text node kind, its in-place editor, and the text
|
|
4
|
+
and sticky-note tools, as presets an app turns on beside core's own.
|
|
5
|
+
|
|
6
|
+
Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic
|
|
7
|
+
scene-graph engine for React. See the
|
|
8
|
+
[API reference](https://orochi235.github.io/weasel/#pkg/text-tools).
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
npm install @weasel-js/text-tools
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Core knows no text. A canvas whose scene holds text nodes (data with a string
|
|
15
|
+
`text`) turns them on with `textPreset`:
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
import { SceneCanvas } from '@weasel-js/core';
|
|
19
|
+
import { textPreset, textToolsPreset } from '@weasel-js/text-tools';
|
|
20
|
+
import { drawPreset } from '@weasel-js/editing';
|
|
21
|
+
|
|
22
|
+
<SceneCanvas scene={scene} features={[drawPreset, textToolsPreset]} />;
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
| Preset | What it adds |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `textPreset` | the `kit:text` painter, whose glyphs are its outline for booleans and Create Outlines; `'text'` routing and properties; the `text` and `sticky` inserts; the canvas's own editor and the `textEdit` dep; `enterTextEdit`, a double-click opening text in place, and a click opening a path effect's hidden text; plain-text paste |
|
|
28
|
+
| `createTextPreset({ editor })` | the same, with the editor configured by `useSceneTextEdit`'s options, or `editor: false` for none |
|
|
29
|
+
| `textToolsPreset` | the text and sticky-note tools, with `textPreset` |
|
|
30
|
+
| `whiteboardPreset` | the pencil, text and the sticky note on an open canvas, with view, pick, move, resize and edit |
|
|
31
|
+
|
|
32
|
+
A canvas taking its tools through `<SceneCanvas tools>` gets the same two from
|
|
33
|
+
`useTextToolsTools()`, beside `textPreset`. A scene drawn with no canvas
|
|
34
|
+
(`renderSceneToPixels`, an export) paints text once `TEXT_PAINTER` is
|
|
35
|
+
registered for it: `nodeShapesOf(scene).register(TEXT_PAINTER)`.
|
|
36
|
+
|
|
37
|
+
The text engine itself (runs, styles, layout, measurement, glyph outlines) is
|
|
38
|
+
`@weasel-js/text`; the DOM editing surface is `@weasel-js/text-dom`.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,578 @@
|
|
|
1
|
+
import { SceneNode, View, NodePaintCtx, NodeShapeEntry, RectPose, InheritedPaint, Scene, MinSize, InsertNodeFactory, InsertToolOptions, Tool, FeaturePreset, NodeRoutingEntry, ToolSet, NodeOutline, EffectItem, NodePropertiesEntry, SceneBatchOptions, RenderLayer, ContentHandlerEntry } from '@weasel-js/core';
|
|
2
|
+
import { DrawCommand } from '@weasel-js/renderer';
|
|
3
|
+
import * as _weasel_js_paint from '@weasel-js/paint';
|
|
4
|
+
import { Fill, Inherit, Stroke, Paint } from '@weasel-js/paint';
|
|
5
|
+
import * as _weasel_js_routing from '@weasel-js/routing';
|
|
6
|
+
import { Point2, ToolOptions, Action } from '@weasel-js/routing';
|
|
7
|
+
import { TextStyle, StyledRun, TextVerticalAlign, TextFit, TextPose, TextPaint, TextOutlineSource } from '@weasel-js/text';
|
|
8
|
+
import { Path, Rect, PathInWorldPose } from '@weasel-js/geom';
|
|
9
|
+
import { UseTextEditReturn } from '@weasel-js/text-dom';
|
|
10
|
+
|
|
11
|
+
/** A scene `drawOne` that leaves out one node's glyphs. */
|
|
12
|
+
type EditingDrawOne = <TNode extends SceneNode<unknown, string, unknown>>(node: TNode, pose: unknown, view?: View, ctx?: NodePaintCtx) => DrawCommand[];
|
|
13
|
+
/** `base`, `defaultDrawOne` by default, less the text commands of the node `editingId` names. */
|
|
14
|
+
declare function drawOneEditing(editingId: string | null, base?: EditingDrawOne): EditingDrawOne;
|
|
15
|
+
/** `cmds` with every text command gone, at any depth, and any group left
|
|
16
|
+
* empty by it — a clipped node's glyphs ride in one. What the canvas keeps of
|
|
17
|
+
* a node an editor's overlay stands in for. */
|
|
18
|
+
declare function withoutText(cmds: readonly DrawCommand[]): DrawCommand[];
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* What a text node with a `background` draws around its box: an edge in a
|
|
22
|
+
* shade of the background, and a shadow under it. Described once here, and
|
|
23
|
+
* drawn by the canvas painter and written by the SVG export from it.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/** A rule just inside a text node's box, in its background's color mixed toward black. */
|
|
27
|
+
interface TextEdge {
|
|
28
|
+
/** World units. */
|
|
29
|
+
width: number;
|
|
30
|
+
/** How far toward black, 0..1, mixed in OKLab, so the edge keeps the background's hue. */
|
|
31
|
+
shade: number;
|
|
32
|
+
}
|
|
33
|
+
/** The shadow a text node's background casts: black at `alpha`, offset and blurred in world units. */
|
|
34
|
+
interface TextShadow {
|
|
35
|
+
x: number;
|
|
36
|
+
y: number;
|
|
37
|
+
blur: number;
|
|
38
|
+
alpha: number;
|
|
39
|
+
}
|
|
40
|
+
/** A text node's frame, ready to draw: each part `null` when there is none. */
|
|
41
|
+
interface TextFrame {
|
|
42
|
+
/** Filled in `color`, each at `opacity`, under the background. */
|
|
43
|
+
shadow: {
|
|
44
|
+
paths: Path[];
|
|
45
|
+
color: string;
|
|
46
|
+
opacity: number;
|
|
47
|
+
} | null;
|
|
48
|
+
/** Stroked in `color` at `width`, over the background. */
|
|
49
|
+
edge: {
|
|
50
|
+
path: Path;
|
|
51
|
+
color: string;
|
|
52
|
+
width: number;
|
|
53
|
+
} | null;
|
|
54
|
+
}
|
|
55
|
+
/** `background`'s color mixed `shade` of the way to black, or `null` for a background with no single color. */
|
|
56
|
+
declare function edgeColor(background: Fill, shade: number): string | null;
|
|
57
|
+
/** The frame of a text node with `d`'s background, edge and shadow, round `box`. */
|
|
58
|
+
declare function textFrameOf(d: {
|
|
59
|
+
background?: Fill | null;
|
|
60
|
+
edge?: TextEdge;
|
|
61
|
+
shadow?: TextShadow;
|
|
62
|
+
}, box: Rect): TextFrame;
|
|
63
|
+
|
|
64
|
+
/** The `data` a `kit:text` node carries. */
|
|
65
|
+
interface TextNodeData {
|
|
66
|
+
text: string;
|
|
67
|
+
style?: TextStyle;
|
|
68
|
+
runs?: readonly StyledRun[];
|
|
69
|
+
fill?: Fill | Inherit | null;
|
|
70
|
+
stroke?: Stroke | Inherit | null;
|
|
71
|
+
verticalAlign?: TextVerticalAlign;
|
|
72
|
+
/** Paint for the whole pose box, drawn under the glyphs. `fill` is the
|
|
73
|
+
* glyphs' own paint, so a box behind them needs a key of its own. */
|
|
74
|
+
background?: Fill | null;
|
|
75
|
+
/** World units between the pose box and the box the text lays out in, on
|
|
76
|
+
* every side. */
|
|
77
|
+
padding?: number;
|
|
78
|
+
/** What happens to text that runs past the pose box: `'visible'` (the
|
|
79
|
+
* default) draws it there, `'clip'` cuts it at the box's edge. */
|
|
80
|
+
overflow?: TextOverflow;
|
|
81
|
+
/** `'shrink'` sets the text at the largest size, at most its own, whose
|
|
82
|
+
* lines fit the box inside `padding`. Default `'none'`. */
|
|
83
|
+
fit?: TextFit;
|
|
84
|
+
/** A rule just inside the box in a shade of `background`. Needs a solid background. */
|
|
85
|
+
edge?: TextEdge;
|
|
86
|
+
/** The shadow `background` casts. Needs a background. */
|
|
87
|
+
shadow?: TextShadow;
|
|
88
|
+
}
|
|
89
|
+
/** How a text node treats lines that run past its box. */
|
|
90
|
+
type TextOverflow = 'visible' | 'clip';
|
|
91
|
+
/** The box a text node's lines lay out in: its pose box, inset by
|
|
92
|
+
* `data.padding` and never past its center. */
|
|
93
|
+
declare function textBoxOf(d: Pick<TextNodeData, 'padding'>, p: RectPose): {
|
|
94
|
+
x: number;
|
|
95
|
+
y: number;
|
|
96
|
+
width: number;
|
|
97
|
+
height: number;
|
|
98
|
+
};
|
|
99
|
+
/** A `kit:text` node as the `TextPose` every text consumer reads, in the box
|
|
100
|
+
* {@link textBoxOf} insets. The stroke goes through the same resolver every
|
|
101
|
+
* other node kind's does, so one carrying no paint is dropped here rather
|
|
102
|
+
* than throwing in the renderer. */
|
|
103
|
+
declare function textPoseOf(d: TextNodeData, p: RectPose, inherited?: InheritedPaint): TextPose;
|
|
104
|
+
/** The node shape that paints a text node: one whose data carries a `text` string, drawn at its box pose. */
|
|
105
|
+
declare const TEXT_PAINTER: NodeShapeEntry<unknown, RectPose>;
|
|
106
|
+
/** The view scale `d` lays out at: `scale` when its style or a run sizes
|
|
107
|
+
* something in `{ px }`, else 1, so world-sized text keeps its memo through a zoom. */
|
|
108
|
+
declare function textLayoutScale(d: Pick<TextNodeData, 'style' | 'runs'>, scale: number | undefined): number;
|
|
109
|
+
|
|
110
|
+
/** Shape the default projections expect `data` to satisfy. All fields
|
|
111
|
+
* optional so any object satisfies the constraint — projections fill in
|
|
112
|
+
* the gaps for non-default shapes. */
|
|
113
|
+
interface DefaultTextData {
|
|
114
|
+
text?: string;
|
|
115
|
+
style?: TextStyle;
|
|
116
|
+
runs?: readonly StyledRun[];
|
|
117
|
+
fill?: Fill | Inherit | null;
|
|
118
|
+
stroke?: Stroke | Inherit | null;
|
|
119
|
+
verticalAlign?: TextVerticalAlign;
|
|
120
|
+
padding?: number;
|
|
121
|
+
overflow?: TextOverflow;
|
|
122
|
+
fit?: TextFit;
|
|
123
|
+
}
|
|
124
|
+
/** All-optional projections + fontSize fallback. */
|
|
125
|
+
interface UseSceneTextEditOptions<TData> {
|
|
126
|
+
/**
|
|
127
|
+
* Is this node text? A double-click opens an edit only on a node that
|
|
128
|
+
* answers yes, and passes through any other to the text under it. Default:
|
|
129
|
+
* `isTextData`, the test `inferredNodeRouting` classifies a text node by. Pass one when `getText` reads some other shape.
|
|
130
|
+
*/
|
|
131
|
+
isText?: (data: TData) => boolean;
|
|
132
|
+
/** Read plain text from `data`. Default: `data.text ?? ''`. */
|
|
133
|
+
getText?: (data: TData) => string;
|
|
134
|
+
/** Read style from `data`. Default: `data.style`. */
|
|
135
|
+
getStyle?: (data: TData) => TextStyle | undefined;
|
|
136
|
+
/** Read the node's paint from `data`. Default: `data.fill` / `data.stroke`. */
|
|
137
|
+
getPaint?: (data: TData) => TextPaint | undefined;
|
|
138
|
+
/** Read rich-text runs from `data`. Default: `data.runs`. */
|
|
139
|
+
getRuns?: (data: TData) => readonly StyledRun[] | undefined;
|
|
140
|
+
/** Read the box vertical alignment from `data`. Default: `data.verticalAlign`. */
|
|
141
|
+
getVerticalAlign?: (data: TData) => TextVerticalAlign | undefined;
|
|
142
|
+
/** Read the inset from the node's box to its text from `data`. Default: `data.padding`. */
|
|
143
|
+
getPadding?: (data: TData) => number | undefined;
|
|
144
|
+
/** Read whether the node cuts its text at its box from `data`. The overlay
|
|
145
|
+
* then does too, and scrolls the text in the box while it is edited.
|
|
146
|
+
* Default: `data.overflow`. */
|
|
147
|
+
getOverflow?: (data: TData) => TextOverflow | undefined;
|
|
148
|
+
/** Read how the node's text size answers to its box from `data`. The overlay
|
|
149
|
+
* sets the text at the size the canvas fits it to. Default: `data.fit`. */
|
|
150
|
+
getFit?: (data: TData) => TextFit | undefined;
|
|
151
|
+
/** Produce updated data with new text. Default: `{ ...data, text }`. */
|
|
152
|
+
setText?: (data: TData, text: string) => TData;
|
|
153
|
+
/** Produce updated data with new runs. Default: `{ ...data, runs }`. */
|
|
154
|
+
setRuns?: (data: TData, runs: StyledRun[]) => TData;
|
|
155
|
+
/**
|
|
156
|
+
* Produce updated data with a new node-wide style. Default:
|
|
157
|
+
* `{ ...data, style }`. Written only when a range toggle has to *clear* a
|
|
158
|
+
* flag the node itself sets — the run algebra is additive, so that edit
|
|
159
|
+
* lowers the node flag and raises it on the runs outside the range. See
|
|
160
|
+
* `useTextEdit`'s `setStyle`.
|
|
161
|
+
*
|
|
162
|
+
* An edit's text, runs, and style are folded through these three and
|
|
163
|
+
* written as one `scene.update`, so a commit is one undo step.
|
|
164
|
+
*/
|
|
165
|
+
setStyle?: (data: TData, style: TextStyle) => TData;
|
|
166
|
+
/**
|
|
167
|
+
* The view to project the overlay through. Omit it and the view is read
|
|
168
|
+
* live from the weasel canvas mounted inside `container` (the first, when
|
|
169
|
+
* there are several). With no canvas there, the node's world box is passed
|
|
170
|
+
* through as screen pixels.
|
|
171
|
+
*
|
|
172
|
+
* A thunk is re-read on every projection; a plain `View` is the value from
|
|
173
|
+
* the render that supplied it.
|
|
174
|
+
*/
|
|
175
|
+
view?: View | (() => View);
|
|
176
|
+
/**
|
|
177
|
+
* Forwarded to `useTextEdit`: is `el` part of the editor's own chrome?
|
|
178
|
+
* Focus moving into it does not end the edit. Wire it to whatever renders
|
|
179
|
+
* the character controls.
|
|
180
|
+
*/
|
|
181
|
+
isEditorChrome?: (el: Element) => boolean;
|
|
182
|
+
/** Forwarded to `useTextEdit`: what Escape does to the edit. */
|
|
183
|
+
escape?: 'cancel' | 'commit';
|
|
184
|
+
/** Forwarded to `useTextEdit`: how long an edit waits for its face. */
|
|
185
|
+
fontHold?: number;
|
|
186
|
+
/** Forwarded to `useTextEdit`: called as an edit of the node `id` opens,
|
|
187
|
+
* whichever way it was started. */
|
|
188
|
+
onStart?: (id: string) => void;
|
|
189
|
+
/** Forwarded to `useTextEdit`: called as the edit of `id` closes, after
|
|
190
|
+
* any commit has been written to the scene. */
|
|
191
|
+
onEnd?: (id: string) => void;
|
|
192
|
+
}
|
|
193
|
+
/** Return shape extends `UseTextEditReturn` with what the `textEdit` dep
|
|
194
|
+
* answers: a double-click on a canvas inside `container` reaches the editor
|
|
195
|
+
* through it, with no handler of the host's. */
|
|
196
|
+
interface UseSceneTextEditReturn extends UseTextEditReturn {
|
|
197
|
+
/** The top-most unlocked text node at world point `at`, and the caret at
|
|
198
|
+
* the glyph there: what `TextEditDep.textAt` wants. */
|
|
199
|
+
textAt: (at: Point2) => {
|
|
200
|
+
id: string;
|
|
201
|
+
caret: number;
|
|
202
|
+
} | null;
|
|
203
|
+
/** The `isText` option asked of the node with this id: what
|
|
204
|
+
* `TextEditDep.isTextNode` wants, so both ways into an edit agree. */
|
|
205
|
+
isTextNode: (id: string) => boolean;
|
|
206
|
+
/**
|
|
207
|
+
* `defaultDrawOne`, less the glyphs of the node being edited: the overlay
|
|
208
|
+
* stands in for its text, and the rest of the node, a `background` among
|
|
209
|
+
* it, goes on painting. A `<SceneCanvas>` inside `container` drawing this
|
|
210
|
+
* scene already leaves those glyphs out; this is for anything else that
|
|
211
|
+
* draws the node.
|
|
212
|
+
*/
|
|
213
|
+
drawOne: EditingDrawOne;
|
|
214
|
+
}
|
|
215
|
+
/** Wire in-place text editing on a scene: mounts a DOM editing overlay over
|
|
216
|
+
* the node being edited and writes the result back as an undoable op.
|
|
217
|
+
* `<SceneCanvas>`'s own editor stands down for any canvas inside `container`
|
|
218
|
+
* and answers its `textEdit` dep with this one, so the canvas's double-click
|
|
219
|
+
* (`enterTextEdit.doubleClick`) and a text tool open this editor, and such a
|
|
220
|
+
* canvas leaves out the glyphs of the node being edited. */
|
|
221
|
+
declare function useSceneTextEdit<TData extends DefaultTextData, TLayer extends string, TPose extends RectPose = RectPose>(scene: Scene<TData, TLayer, TPose>, container: HTMLElement | null, options?: UseSceneTextEditOptions<TData>): UseSceneTextEditReturn;
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* The canvas's own text editor: the one `enterTextEdit` reaches, from a text
|
|
225
|
+
* or sticky tool or a double-click on a text node, when the host has wired
|
|
226
|
+
* none of its own. `textPreset` mounts it inside the canvas. It stands down for
|
|
227
|
+
* a host editor: a `useSceneTextEdit` whose container holds the canvas, which
|
|
228
|
+
* the `textEdit` dep then answers with, or a `textEdit` dep registered over it.
|
|
229
|
+
*/
|
|
230
|
+
|
|
231
|
+
/** The canvas's own editor: `useSceneTextEdit`'s options, or `false` for none. */
|
|
232
|
+
type CanvasTextEditorOptions<TData = DefaultTextData> = false | UseSceneTextEditOptions<TData>;
|
|
233
|
+
|
|
234
|
+
/** How a sticky note looks as it is made, named as the text node it becomes
|
|
235
|
+
* names them. Every field has a default, in {@link STICKY_DEFAULTS}. */
|
|
236
|
+
interface StickyStyle {
|
|
237
|
+
/** The note itself, painted over its whole box. */
|
|
238
|
+
background?: Fill;
|
|
239
|
+
/** The text's paint. */
|
|
240
|
+
fill?: Fill;
|
|
241
|
+
/** World units from the note's edge to its text, on every side. */
|
|
242
|
+
padding?: number;
|
|
243
|
+
/** Typography for the note's text. */
|
|
244
|
+
style?: TextStyle;
|
|
245
|
+
verticalAlign?: TextVerticalAlign;
|
|
246
|
+
/** What happens to text that outgrows the note. */
|
|
247
|
+
overflow?: TextOverflow;
|
|
248
|
+
/** The rule round the note, in a darker shade of its paper. */
|
|
249
|
+
edge?: TextEdge;
|
|
250
|
+
/** The shadow the note casts. */
|
|
251
|
+
shadow?: TextShadow;
|
|
252
|
+
/** The smallest note a drag makes or a resize leaves, in world units. */
|
|
253
|
+
minSize?: MinSize;
|
|
254
|
+
/** The note a click makes, centered on the click, in world units. A drag
|
|
255
|
+
* makes the note it draws. */
|
|
256
|
+
size?: {
|
|
257
|
+
width: number;
|
|
258
|
+
height: number;
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
/** A sticky insert's extras: the tool's {@link StickyStyle}, and its `paper` and `ink` options, the paints that
|
|
262
|
+
* stand over `background` and `fill`. */
|
|
263
|
+
type StickyLook = StickyStyle & {
|
|
264
|
+
paper?: Paint | null;
|
|
265
|
+
ink?: Paint | null;
|
|
266
|
+
};
|
|
267
|
+
/** The look a sticky note takes for any field its tool leaves out. */
|
|
268
|
+
declare const STICKY_DEFAULTS: {
|
|
269
|
+
readonly background: {
|
|
270
|
+
readonly paint: {
|
|
271
|
+
readonly kind: "solid";
|
|
272
|
+
readonly color: "#fff1a6ff";
|
|
273
|
+
};
|
|
274
|
+
};
|
|
275
|
+
readonly fill: _weasel_js_paint.PaintedFill;
|
|
276
|
+
readonly padding: 12;
|
|
277
|
+
readonly style: {
|
|
278
|
+
readonly fontSize: 18;
|
|
279
|
+
readonly align: "center";
|
|
280
|
+
readonly wrap: true;
|
|
281
|
+
};
|
|
282
|
+
readonly verticalAlign: "center";
|
|
283
|
+
readonly overflow: "clip";
|
|
284
|
+
readonly edge: {
|
|
285
|
+
readonly width: 1;
|
|
286
|
+
readonly shade: 0.18;
|
|
287
|
+
};
|
|
288
|
+
readonly shadow: {
|
|
289
|
+
readonly x: 0;
|
|
290
|
+
readonly y: 2;
|
|
291
|
+
readonly blur: 6;
|
|
292
|
+
readonly alpha: 0.18;
|
|
293
|
+
};
|
|
294
|
+
readonly minSize: {
|
|
295
|
+
readonly width: 48;
|
|
296
|
+
readonly height: 48;
|
|
297
|
+
};
|
|
298
|
+
readonly size: {
|
|
299
|
+
readonly width: 160;
|
|
300
|
+
readonly height: 160;
|
|
301
|
+
};
|
|
302
|
+
};
|
|
303
|
+
/**
|
|
304
|
+
* A sticky note's `data`: a text node with a `background`, so the `kit:text`
|
|
305
|
+
* painter draws it and the text editor edits it with no sticky case of its
|
|
306
|
+
* own. `look` is the `sticky` insert's extras, which carry the tool's
|
|
307
|
+
* {@link StickyStyle}.
|
|
308
|
+
*/
|
|
309
|
+
declare function stickyData(look: StickyLook & {
|
|
310
|
+
text?: string;
|
|
311
|
+
}): TextNodeData & {
|
|
312
|
+
minSize: MinSize;
|
|
313
|
+
};
|
|
314
|
+
/** The `sticky` insert as an `InsertNodeFactory`: what `textPreset` installs, for a canvas that wraps it — to tag
|
|
315
|
+
* the data with a `kind`, say — under `insertNodeFactories`. An empty note opens for typing, as text does. */
|
|
316
|
+
declare const stickyNodeFactory: InsertNodeFactory;
|
|
317
|
+
|
|
318
|
+
/** Options for `useStickyTool`: the look of the notes it makes, and the
|
|
319
|
+
* insert behaviors every drag-to-insert tool takes. Keep object options
|
|
320
|
+
* stable across renders: a new one rebuilds the tool. */
|
|
321
|
+
interface UseStickyToolOptions extends InsertToolOptions, StickyStyle {
|
|
322
|
+
}
|
|
323
|
+
/** The sticky tool's options: the note's paper and its ink, its own rather than shared with the shape tools.
|
|
324
|
+
* Both inserts read them, the drag's and the click's. */
|
|
325
|
+
declare const STICKY_TOOL_OPTIONS: ToolOptions;
|
|
326
|
+
/**
|
|
327
|
+
* Sticky-note tool. A drag draws a note through `insertAction`, a click
|
|
328
|
+
* places one of `size` through `placeAction`, and either drops into the new
|
|
329
|
+
* note's caret. Neither makes a note smaller than `minSize`, and the note
|
|
330
|
+
* keeps it as the floor a resize stops at. A click on a selected note edits it.
|
|
331
|
+
*
|
|
332
|
+
* The note is minted by the `insert` dep's `sticky` kind (`textPreset`'s
|
|
333
|
+
* `stickyNodeFactory`), as a text node with a `background` (see `stickyData`); the look rides on the bindings' params
|
|
334
|
+
* as that insert's extras, and its paper and ink are the tool's options
|
|
335
|
+
* (`background` and `fill` set their defaults). A consumer wanting its own node overrides the dep
|
|
336
|
+
* (`insertNodeFactories.sticky`), not the tool.
|
|
337
|
+
*/
|
|
338
|
+
declare function createStickyTool(options?: UseStickyToolOptions): Tool;
|
|
339
|
+
/** {@link createStickyTool}, rebuilt only when an option changes. */
|
|
340
|
+
declare function useStickyTool(options?: UseStickyToolOptions): Tool;
|
|
341
|
+
|
|
342
|
+
/** Routes a leaf whose `data.text` is a string as `'text'`, ahead of the canvas's own routing, so an
|
|
343
|
+
* SVG-imported text node carrying a fallback `path` routes to text edit. */
|
|
344
|
+
declare const textNodeRouting: NodeRoutingEntry;
|
|
345
|
+
/** Options for {@link createTextPreset}. */
|
|
346
|
+
interface TextPresetOptions<TData = DefaultTextData> {
|
|
347
|
+
/** The canvas's own editor: `useSceneTextEdit`'s options, or `false` for none. Default `{}`. It mounts its
|
|
348
|
+
* overlay in the canvas's offset parent, so the canvas wants a positioned ancestor, and stands down for a
|
|
349
|
+
* host's own editor: a `useSceneTextEdit` whose container holds the canvas, or a `textEdit` dep a child of
|
|
350
|
+
* the canvas registers. Wire one of those for character controls, which read the edit's state. */
|
|
351
|
+
editor?: CanvasTextEditorOptions<TData>;
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* The text node kind and its editing, configured by `options`: the `kit:text` painter, whose glyphs are its
|
|
355
|
+
* outline; `'text'` routing and properties; the `text` and `sticky` inserts; the canvas's own editor and the
|
|
356
|
+
* `textEdit` dep; `enterTextEdit`, a double-click opening text in place (`editTextAt`), and a click on a path
|
|
357
|
+
* effect's hidden text opening it (`editEffectText`); and plain-text paste.
|
|
358
|
+
*/
|
|
359
|
+
declare function createTextPreset<TData = DefaultTextData>(options?: TextPresetOptions<TData>): FeaturePreset;
|
|
360
|
+
/** {@link createTextPreset} with its defaults. */
|
|
361
|
+
declare const textPreset: FeaturePreset;
|
|
362
|
+
/** Options for {@link createTextToolsPreset}: the insert behaviors both tools take, and the sticky notes' look. */
|
|
363
|
+
interface TextToolsPresetOptions extends Pick<UseStickyToolOptions, 'behaviors' | 'share'> {
|
|
364
|
+
sticky?: Omit<UseStickyToolOptions, 'behaviors' | 'share'>;
|
|
365
|
+
/** The text preset the tools need, for a canvas configuring its editor. Default {@link textPreset}. */
|
|
366
|
+
text?: FeaturePreset;
|
|
367
|
+
}
|
|
368
|
+
/** The text and sticky-note tools, with the text preset whose actions and inserts they bind. */
|
|
369
|
+
declare function createTextToolsPreset(options?: TextToolsPresetOptions): FeaturePreset;
|
|
370
|
+
/** {@link createTextToolsPreset} with its defaults. */
|
|
371
|
+
declare const textToolsPreset: FeaturePreset;
|
|
372
|
+
/**
|
|
373
|
+
* A whiteboard: text and the sticky note on an open canvas you pan and zoom, with the select tool, moving,
|
|
374
|
+
* resizing and editing what is on it. A note is the sticky tool's, a text node with a `background`. A pencil is
|
|
375
|
+
* `@weasel-js/path-tools`' `usePencilTool`, passed in `tools`.
|
|
376
|
+
*/
|
|
377
|
+
declare const whiteboardPreset: FeaturePreset;
|
|
378
|
+
|
|
379
|
+
/** The ids {@link useTextToolsTools} keys its tools by. */
|
|
380
|
+
type TextToolId = 'text' | 'sticky';
|
|
381
|
+
/** The text tools: text and the sticky note. A palette groups them as `type`. */
|
|
382
|
+
declare const TEXT_TOOLS: ToolSet<TextToolId>;
|
|
383
|
+
/** The tools a whiteboard makes things with: text and the sticky note. A pencil is `@weasel-js/path-tools`'. */
|
|
384
|
+
declare const WHITEBOARD_TOOLS: ToolSet<TextToolId>;
|
|
385
|
+
/**
|
|
386
|
+
* Every tool in {@link TEXT_TOOLS}, keyed by id, for `<SceneCanvas tools>` beside `textPreset`, whose actions
|
|
387
|
+
* they bind. `textToolsPreset` mounts the same tools without a hook.
|
|
388
|
+
*/
|
|
389
|
+
declare function useTextToolsTools(options?: UseStickyToolOptions): Record<TextToolId, Tool>;
|
|
390
|
+
|
|
391
|
+
/** A text node's glyphs as its outline: what `kit:text` answers for `NodeShapeEntry.outline`. */
|
|
392
|
+
|
|
393
|
+
/** `d`'s glyphs laid in `box`, the box its padding insets, wearing its paint with `inherited`'s resolved. */
|
|
394
|
+
declare function textOutlineOf(d: TextNodeData, box: PathInWorldPose, inherited?: InheritedPaint): NodeOutline;
|
|
395
|
+
|
|
396
|
+
/**
|
|
397
|
+
* A text node as a path effect's items: its first line's grapheme clusters,
|
|
398
|
+
* each one's outlines and decoration rules in its own frame, sized as the node
|
|
399
|
+
* draws them.
|
|
400
|
+
*/
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* The clusters of `data`'s first line as items, laid in `pose`'s box width.
|
|
404
|
+
* The pose's scale grows them; its rotation and skew are dropped, since the
|
|
405
|
+
* path an effect lays them along decides their turn. `[]` while a face's
|
|
406
|
+
* outlines are loading — the load is started, and the font read is noted so
|
|
407
|
+
* the derivation re-runs once it lands.
|
|
408
|
+
*/
|
|
409
|
+
declare function textEffectItems(data: TextOutlineSource, pose: PathInWorldPose): readonly EffectItem[];
|
|
410
|
+
|
|
411
|
+
/** The `text` kind's properties, for a `SelectionPanel` given `textPreset`. */
|
|
412
|
+
declare const TEXT_PROPERTIES: NodePropertiesEntry;
|
|
413
|
+
|
|
414
|
+
/** The `text` insert: an empty box you then type into, or a pasted string, set in the tool's fill. The `kit:text`
|
|
415
|
+
* painter applies the style's defaults when it draws. */
|
|
416
|
+
declare const textNodeFactory: InsertNodeFactory;
|
|
417
|
+
|
|
418
|
+
/**
|
|
419
|
+
* A text edit shown to the scene keystroke by keystroke, for the readers that
|
|
420
|
+
* see a node somewhere besides the overlay: text something derives from, such
|
|
421
|
+
* as the hidden text a path effect lays along a path, or a second view.
|
|
422
|
+
*/
|
|
423
|
+
|
|
424
|
+
/**
|
|
425
|
+
* Options for a batch that makes node `id` for a text edit to fill in: `scene.batch('Add label', add,
|
|
426
|
+
* textEditJoin(id))`. The edit's commit then joins that batch's undo entry, so one undo takes the node and its
|
|
427
|
+
* first text away together. A host's `onEnd` that removes a node left empty passes the same options, and the
|
|
428
|
+
* removal joins too. The run ends with the edit: a later edit of the node is an entry of its own.
|
|
429
|
+
*/
|
|
430
|
+
declare function textEditJoin(id: string): SceneBatchOptions;
|
|
431
|
+
|
|
432
|
+
/**
|
|
433
|
+
* Text RenderLayer for text that is not in a scene: one `textCommandFromPose`
|
|
434
|
+
* command per item, the same command the `kit:text` node painter emits, so an
|
|
435
|
+
* item lays out — and wraps, or doesn't, per its style — as a node would.
|
|
436
|
+
*
|
|
437
|
+
* The GL renderer uses MSDF text. The resolved style's `fontFamily` must
|
|
438
|
+
* be registered via `registerFont(family, variant, metricsUrl, atlasUrl)`
|
|
439
|
+
* from the renderer module *before* the GL backend dispatches this layer.
|
|
440
|
+
* Unregistered families render with a warning and no glyphs (see
|
|
441
|
+
* `TextDrawCommand`'s contract).
|
|
442
|
+
*/
|
|
443
|
+
|
|
444
|
+
/** Options for `createTextLayer`. */
|
|
445
|
+
interface CreateTextLayerOptions<T> {
|
|
446
|
+
id?: string;
|
|
447
|
+
label?: string;
|
|
448
|
+
getTexts: () => readonly T[];
|
|
449
|
+
getPose: (node: T) => TextPose;
|
|
450
|
+
/** Optional per-node hide hook (e.g., suppress while editing). */
|
|
451
|
+
isHidden?: (node: T) => boolean;
|
|
452
|
+
/** When `true`, each text command is wrapped in a clipped group so any
|
|
453
|
+
* overflow beyond the pose's `(width × height)` is hidden. Default
|
|
454
|
+
* `false` (legacy: text can spill outside the declared bounds). Opt-in
|
|
455
|
+
* so existing consumers who rely on overflow keep working. */
|
|
456
|
+
clipToBounds?: boolean;
|
|
457
|
+
}
|
|
458
|
+
/** Build a `RenderLayer` that emits one `TextDrawCommand` per text node. */
|
|
459
|
+
declare function createTextLayer<T>(opts: CreateTextLayerOptions<T>): RenderLayer<unknown>;
|
|
460
|
+
|
|
461
|
+
/**
|
|
462
|
+
* The `textEdit` dep: what opens a text node for editing. This package adds it
|
|
463
|
+
* to routing's `DepSchema`, as a consumer merges its own deps.
|
|
464
|
+
*/
|
|
465
|
+
|
|
466
|
+
/**
|
|
467
|
+
* Dep for `enterTextEditAction`. `textPreset` answers it with the canvas's own
|
|
468
|
+
* editor (`createTextPreset`'s `editor`), or with the editor of a host's
|
|
469
|
+
* `useSceneTextEdit` whose container holds the canvas. A host whose editor's
|
|
470
|
+
* container does not hold the canvas publishes it from inside `<SceneCanvas>`:
|
|
471
|
+
*
|
|
472
|
+
* @example
|
|
473
|
+
* ```ts
|
|
474
|
+
* const textEdit = useSceneTextEdit(scene, container);
|
|
475
|
+
* useDepSource('textEdit', () => ({
|
|
476
|
+
* startEdit: textEdit.startEdit,
|
|
477
|
+
* textAt: textEdit.textAt,
|
|
478
|
+
* isTextNode: textEdit.isTextNode,
|
|
479
|
+
* }));
|
|
480
|
+
* ```
|
|
481
|
+
*/
|
|
482
|
+
interface TextEditDep {
|
|
483
|
+
/** Begin editing the node with `id`. */
|
|
484
|
+
startEdit(id: string, opts?: {
|
|
485
|
+
caret?: number | 'all';
|
|
486
|
+
}): void;
|
|
487
|
+
/**
|
|
488
|
+
* The top-most text node this editor would open at world point `at`, and
|
|
489
|
+
* the caret at the glyph there, or `null` where there is none. A
|
|
490
|
+
* double-click opens what this answers (`enterTextEdit.doubleClick`).
|
|
491
|
+
*/
|
|
492
|
+
textAt(at: Point2): {
|
|
493
|
+
id: string;
|
|
494
|
+
caret: number;
|
|
495
|
+
} | null;
|
|
496
|
+
/**
|
|
497
|
+
* Optional predicate: returns `true` when the node with `id` is a text node.
|
|
498
|
+
* When absent the action fires on any selected node (binding spec is the gate).
|
|
499
|
+
* When present and returning `false`, the invocation is a no-op.
|
|
500
|
+
*/
|
|
501
|
+
isTextNode?(id: string): boolean;
|
|
502
|
+
}
|
|
503
|
+
declare module '@weasel-js/routing' {
|
|
504
|
+
interface DepSchema {
|
|
505
|
+
/**
|
|
506
|
+
* Text-edit dep — activates the in-place text editing overlay. `textPreset`
|
|
507
|
+
* publishes the canvas's own editor, or a host's `useSceneTextEdit`.
|
|
508
|
+
*
|
|
509
|
+
* The optional `isTextNode` predicate guards against entering edit mode on
|
|
510
|
+
* non-text nodes. A binding can pre-filter instead with a
|
|
511
|
+
* `target: 'kind:text:selected'` spec; the guard remains for consumers who
|
|
512
|
+
* bind the broader `'selected-body'` target or opted out of routing.
|
|
513
|
+
*/
|
|
514
|
+
textEdit: TextEditDep;
|
|
515
|
+
}
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
/**
|
|
519
|
+
* Starts in-place text editing on the single selected node. It has no
|
|
520
|
+
* `defaultBinding`: it fires only via `Tool.bindings`.
|
|
521
|
+
*
|
|
522
|
+
* A `'selected-body'` target matches any selected node kind, so the action
|
|
523
|
+
* skips a node `TextEditDep.isTextNode` rejects. With no `isTextNode` it fires
|
|
524
|
+
* unconditionally, and the binding spec is the only gate; a binding can
|
|
525
|
+
* pre-filter with `target: 'kind:text:selected'` instead.
|
|
526
|
+
*/
|
|
527
|
+
declare const enterTextEditAction: Action & {
|
|
528
|
+
requires: string[];
|
|
529
|
+
};
|
|
530
|
+
|
|
531
|
+
/**
|
|
532
|
+
* Opens the top-most text node at the pointer in place, the caret at the glyph
|
|
533
|
+
* there, through the `textEdit` dep. It declines where no text is under the
|
|
534
|
+
* pointer, and where the double-click names a group above the text, whose own
|
|
535
|
+
* double-click enters it, as `enterPathEdit` declines there. `enterTextEdit`
|
|
536
|
+
* opens the selection instead.
|
|
537
|
+
*/
|
|
538
|
+
declare const editTextAtAction: _weasel_js_routing.Action & {
|
|
539
|
+
id: "editTextAt";
|
|
540
|
+
};
|
|
541
|
+
|
|
542
|
+
/** A click on a text-on-path effect's body opens its source text for editing, unless an anchor is under the pointer. */
|
|
543
|
+
declare const editEffectTextAction: _weasel_js_routing.Action & {
|
|
544
|
+
id: "editEffectText";
|
|
545
|
+
};
|
|
546
|
+
|
|
547
|
+
/** The text tool's options: the fill new text is set in, shared under `textFill`. Not the shapes' `fill`: a white
|
|
548
|
+
* shape fill would set white text on a white page. */
|
|
549
|
+
declare const TEXT_TOOL_OPTIONS: _weasel_js_routing.ToolOptions;
|
|
550
|
+
/** Text tool. Drag-rect insertion is owned end-to-end by the dispatcher's
|
|
551
|
+
* `insertAction` (kind: `'text'`); click-on-selected-text-node enters edit
|
|
552
|
+
* mode via the `enterTextEdit` action.
|
|
553
|
+
*
|
|
554
|
+
* Its actions, the `text` insert and the `textEdit` dep come with
|
|
555
|
+
* `textPreset`. Custom node factories and hit gating belong on those deps,
|
|
556
|
+
* not on the tool. */
|
|
557
|
+
declare function createTextTool(options?: InsertToolOptions): Tool;
|
|
558
|
+
/** {@link createTextTool}, rebuilt only when an option changes. */
|
|
559
|
+
declare function useTextTool(options?: InsertToolOptions): Tool;
|
|
560
|
+
|
|
561
|
+
/** Options for {@link createTextHandler}. */
|
|
562
|
+
interface TextHandlerOptions {
|
|
563
|
+
/** Size of a string's layout box in world units. Default
|
|
564
|
+
* `measureTextBounds`, which reads the registered font. */
|
|
565
|
+
measure?: (text: string) => {
|
|
566
|
+
width: number;
|
|
567
|
+
height: number;
|
|
568
|
+
};
|
|
569
|
+
}
|
|
570
|
+
/** Build the plain-text content handler; {@link textContentHandler} is the one
|
|
571
|
+
* with the default measurer. */
|
|
572
|
+
declare function createTextHandler(opts?: TextHandlerOptions): ContentHandlerEntry;
|
|
573
|
+
/** Turns pasted or dropped plain text into a text node sized to the string. A kit handler, so a
|
|
574
|
+
* canvas with the `ingest` feature takes text unless its `ingestion.kitHandlers` omits it. */
|
|
575
|
+
declare const textContentHandler: ContentHandlerEntry;
|
|
576
|
+
|
|
577
|
+
export { STICKY_DEFAULTS, STICKY_TOOL_OPTIONS, TEXT_PAINTER, TEXT_PROPERTIES, TEXT_TOOLS, TEXT_TOOL_OPTIONS, WHITEBOARD_TOOLS, createStickyTool, createTextHandler, createTextLayer, createTextPreset, createTextTool, createTextToolsPreset, drawOneEditing, edgeColor, editEffectTextAction, editTextAtAction, enterTextEditAction, stickyData, stickyNodeFactory, textBoxOf, textContentHandler, textEditJoin, textEffectItems, textFrameOf, textLayoutScale, textNodeFactory, textNodeRouting, textOutlineOf, textPoseOf, textPreset, textToolsPreset, useSceneTextEdit, useStickyTool, useTextTool, useTextToolsTools, whiteboardPreset, withoutText };
|
|
578
|
+
export type { CanvasTextEditorOptions, CreateTextLayerOptions, DefaultTextData, EditingDrawOne, StickyLook, StickyStyle, TextEdge, TextEditDep, TextFrame, TextHandlerOptions, TextNodeData, TextOverflow, TextPresetOptions, TextShadow, TextToolId, TextToolsPresetOptions, UseSceneTextEditOptions, UseSceneTextEditReturn, UseStickyToolOptions };
|