@kition/kit-editor 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/README.md +103 -2
- package/dist/LICENSE +177 -0
- package/dist/THIRD_PARTY_NOTICES +28 -0
- package/dist/assets/kitEngine.worker-Bb4qhbsX.js +13038 -0
- package/dist/chunks/workspaceTree-CpJ2i9hy.js +23 -0
- package/dist/index.js +6434 -0
- package/dist/styles.css +807 -0
- package/dist/types/src/CommandDialog.d.ts +22 -0
- package/dist/types/src/CommentsPanel.d.ts +45 -0
- package/dist/types/src/CustomizeDialog.d.ts +32 -0
- package/dist/types/src/HostButtons.d.ts +11 -0
- package/dist/types/src/RenderFailure.d.ts +7 -0
- package/dist/types/src/TextSink.d.ts +6 -0
- package/dist/types/src/brand.d.ts +2 -0
- package/dist/types/src/catalogMenus.d.ts +27 -0
- package/dist/types/src/chart.d.ts +138 -0
- package/dist/types/src/conflicts.d.ts +12 -0
- package/dist/types/src/drawing.d.ts +83 -0
- package/dist/types/src/editor.d.ts +544 -0
- package/dist/types/src/engine/KitCanvas.d.ts +70 -0
- package/dist/types/src/engine/createKitFile.d.ts +12 -0
- package/dist/types/src/engine/decorations.d.ts +14 -0
- package/dist/types/src/engine/engineOverlays.d.ts +197 -0
- package/dist/types/src/engine/engineTools.d.ts +116 -0
- package/dist/types/src/engine/kitDraft.d.ts +70 -0
- package/dist/types/src/engine/kitEngine.d.ts +370 -0
- package/dist/types/src/engine/kitEngine.worker.d.ts +30 -0
- package/dist/types/src/engine/kitHost.d.ts +41 -0
- package/dist/types/src/engine/kitModel.d.ts +32 -0
- package/dist/types/src/engine/kitModelRunner.d.ts +99 -0
- package/dist/types/src/engine/kitModule.d.ts +173 -0
- package/dist/types/src/engine/kitShortcuts.d.ts +32 -0
- package/dist/types/src/engine/kitTools.d.ts +79 -0
- package/dist/types/src/engine/lentFiles.d.ts +29 -0
- package/dist/types/src/engine/rasterViewport.d.ts +178 -0
- package/dist/types/src/engine/readOnly.d.ts +78 -0
- package/dist/types/src/engine/refusal.d.ts +39 -0
- package/dist/types/src/engine/replica.d.ts +23 -0
- package/dist/types/src/engine/useKitDocument.d.ts +154 -0
- package/dist/types/src/engine/workerRelay.d.ts +62 -0
- package/dist/types/src/files.d.ts +74 -0
- package/dist/types/src/frame/EditorFrame.d.ts +74 -0
- package/dist/types/src/frame/FocusBar.d.ts +10 -0
- package/dist/types/src/frame/MenuNodes.d.ts +20 -0
- package/dist/types/src/frame/MenuRibbon.d.ts +8 -0
- package/dist/types/src/frame/ModeButton.d.ts +7 -0
- package/dist/types/src/frame/menus.d.ts +64 -0
- package/dist/types/src/frame/modes.d.ts +51 -0
- package/dist/types/src/frame/useFrameLayout.d.ts +34 -0
- package/dist/types/src/host.d.ts +127 -0
- package/dist/types/src/index.d.ts +84 -0
- package/dist/types/src/ink.d.ts +26 -0
- package/dist/types/src/lease.d.ts +53 -0
- package/dist/types/src/oneInFlight.d.ts +7 -0
- package/dist/types/src/phrases.d.ts +25 -0
- package/dist/types/src/presence.d.ts +79 -0
- package/dist/types/src/strings.d.ts +6 -0
- package/dist/types/src/toolIcons.d.ts +32 -0
- package/dist/types/src/uiCatalog.d.ts +59 -0
- package/dist/types/src/uiConfig.d.ts +53 -0
- package/dist/types/src/uiContext.d.ts +65 -0
- package/dist/types/src/uiStore.d.ts +20 -0
- package/dist/types/src/useCommentAnchors.d.ts +29 -0
- package/dist/types/src/useKitSession.d.ts +115 -0
- package/dist/types/src/workspaceTree.d.ts +5 -0
- package/dist/workspaceTree.js +1 -0
- package/package.json +43 -3
|
@@ -0,0 +1,544 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The parts every kit editor shares: the engine's commands (which can run, running one, a
|
|
3
|
+
* parameters dialog for one that needs values), ribbon buttons and tabs built from them, and the
|
|
4
|
+
* editor shell the frame draws (`frame/EditorFrame.tsx`): the document actions (Undo, Redo, Ask
|
|
5
|
+
* Agent, and Save), the status bar, the dialog and notices, and the standard shortcuts.
|
|
6
|
+
*/
|
|
7
|
+
import { type KeyboardEvent, type ReactNode, type RefObject } from 'react';
|
|
8
|
+
import { type IconComponent } from '@kition/tessera-icons/react';
|
|
9
|
+
import { type RibbonButtonProps } from '@kition/tessera-ui';
|
|
10
|
+
import { type Catalog } from './strings.js';
|
|
11
|
+
import type { Phrases } from './phrases.js';
|
|
12
|
+
import { type HostConnection } from './host.js';
|
|
13
|
+
import type { useKitSession } from './useKitSession.js';
|
|
14
|
+
import type { KitCommand } from './engine/kitModule.js';
|
|
15
|
+
import { type KitCanvasHandle, type KitCanvasView } from './engine/KitCanvas.js';
|
|
16
|
+
import type { RasterDecoration, RasterRect, RasterView, RasterViewportStats } from './engine/rasterViewport.js';
|
|
17
|
+
import { type KitTool } from './engine/kitTools.js';
|
|
18
|
+
import type { useEngineTools } from './engine/engineTools.js';
|
|
19
|
+
export type KitSession<T> = ReturnType<typeof useKitSession<T>>;
|
|
20
|
+
export type KitTools = ReturnType<typeof useEngineTools>;
|
|
21
|
+
export type Strings = (key: string, values?: Record<string, string | number>) => string;
|
|
22
|
+
/** The shell's own strings; a kit's catalogs may override any of them. */
|
|
23
|
+
export declare const KIT_UI_CATALOGS: Record<string, Catalog>;
|
|
24
|
+
/** A kit's strings over the shell's, for `locale` (fallbacks as in `createStrings`). */
|
|
25
|
+
export declare function createKitStrings(catalogs: Record<string, Catalog>, locale: string): Strings;
|
|
26
|
+
/**
|
|
27
|
+
* How an editor reports a failure: `title` says what failed (`commandFailed`, `saveFailed`), and
|
|
28
|
+
* `error` why. The default is an error toast; an editor that ports an app with a status bar
|
|
29
|
+
* passes its own (Film shows every error there, as upstream does).
|
|
30
|
+
*/
|
|
31
|
+
export type KitReport = (title: string, error: unknown) => void;
|
|
32
|
+
export type KitEditorOptions = {
|
|
33
|
+
/** Where failures go; an error toast when unset. */
|
|
34
|
+
report?: KitReport;
|
|
35
|
+
/**
|
|
36
|
+
* The kit's own undo history, when it is more than its engine's: an editor that edits a page
|
|
37
|
+
* replica (`WorkerRelay`) next to its engine has steps in both. The frame's Undo and Redo
|
|
38
|
+
* (buttons, menus, shortcuts, the Focus bar) then show and run this history instead of the
|
|
39
|
+
* engine's `edit.undo` and `edit.redo`, still under the host's configuration.
|
|
40
|
+
*/
|
|
41
|
+
history?: KitHistory;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* A kit's own undo history for the frame (`KitEditorOptions.history`). `undo` and `redo` answer
|
|
45
|
+
* whether they took a step (or a promise of it); `subscribe` calls its listener whenever
|
|
46
|
+
* `canUndo` or `canRedo` may have changed, and answers the unsubscribe.
|
|
47
|
+
*/
|
|
48
|
+
export type KitHistory = {
|
|
49
|
+
canUndo(): boolean;
|
|
50
|
+
canRedo(): boolean;
|
|
51
|
+
undo(): boolean | Promise<boolean>;
|
|
52
|
+
redo(): boolean | Promise<boolean>;
|
|
53
|
+
subscribe(listener: () => void): () => void;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* The engine's commands for an editor: which exist and can run (refreshed after every change),
|
|
57
|
+
* running one (opening its parameters dialog when it needs values and none are given), queries
|
|
58
|
+
* answered as JSON, and saving. `testId` prefixes the test ids of the shared controls.
|
|
59
|
+
*/
|
|
60
|
+
export declare function useKitEditorState<T>(session: KitSession<T>, host: HostConnection, t: Strings, testId: string, phrase?: Phrases,
|
|
61
|
+
/** Values a command's dialog starts with, from where the person is (the current page). */
|
|
62
|
+
defaults?: (command: KitCommand) => Record<string, unknown>, options?: KitEditorOptions): {
|
|
63
|
+
session: {
|
|
64
|
+
run: (command: string, params?: Record<string, unknown>, damage?: RasterRect | null, options?: import(".").KitRunOptions) => Promise<string | null>;
|
|
65
|
+
editedBy: import("./useKitSession.js").KitEditedBy | null;
|
|
66
|
+
comments: ReadonlySet<string>;
|
|
67
|
+
path: string;
|
|
68
|
+
manifest: import(".").KitModuleManifest;
|
|
69
|
+
doc: import(".").KitEngine | null;
|
|
70
|
+
info: import(".").KitEngineInfo | null;
|
|
71
|
+
state: T | null;
|
|
72
|
+
change: import(".").KitChange;
|
|
73
|
+
repaints: import(".").KitRepaints;
|
|
74
|
+
dirty: boolean;
|
|
75
|
+
failure: string | null;
|
|
76
|
+
openMs: number | null;
|
|
77
|
+
saving: boolean;
|
|
78
|
+
conflict: boolean;
|
|
79
|
+
tool: <R>(name: import("./engine/kitEngine.js").KitToolMethod, args?: unknown[], settled?: boolean) => Promise<R | null>;
|
|
80
|
+
commands: () => Promise<never[] | KitCommand[]>;
|
|
81
|
+
disabledCommands: () => Promise<string[] | never[]>;
|
|
82
|
+
save: () => Promise<void>;
|
|
83
|
+
replica: {
|
|
84
|
+
version: () => Promise<ArrayBuffer>;
|
|
85
|
+
exportChanges: (since: ArrayBuffer) => Promise<{
|
|
86
|
+
changes: ArrayBuffer;
|
|
87
|
+
blobs: ArrayBuffer;
|
|
88
|
+
}>;
|
|
89
|
+
importChanges: (changes: ArrayBuffer, blobs: ArrayBuffer) => Promise<unknown>;
|
|
90
|
+
docId: () => Promise<string | null>;
|
|
91
|
+
};
|
|
92
|
+
model: {
|
|
93
|
+
describe: (schema: object | null) => Promise<Record<string, unknown>>;
|
|
94
|
+
version: () => Promise<string>;
|
|
95
|
+
changes: (since: string, schema: object | null) => Promise<import("./engine/kitEngine.js").KitModelChanges>;
|
|
96
|
+
batch: (request: Record<string, unknown>, schema: object | null) => Promise<import("@kition/kit-ui-protocol").ModelBatchResult>;
|
|
97
|
+
};
|
|
98
|
+
draft: {
|
|
99
|
+
open: () => Promise<{
|
|
100
|
+
engine: import(".").KitEngine;
|
|
101
|
+
base: ArrayBuffer;
|
|
102
|
+
}>;
|
|
103
|
+
merge: (changes: ArrayBuffer, blobs: ArrayBuffer, origin: import("@kition/kdm").Origin, schema: object | null) => Promise<import("@kition/kit-ui-protocol").DraftSummary>;
|
|
104
|
+
compare: (changes: ArrayBuffer, schema: object | null) => Promise<import("@kition/kit-ui-protocol").DraftSummary>;
|
|
105
|
+
};
|
|
106
|
+
reopen: () => void;
|
|
107
|
+
keepMine: () => Promise<void>;
|
|
108
|
+
checkFile: (isCurrent?: () => boolean) => Promise<void>;
|
|
109
|
+
holdFile: (stamp: string) => Promise<void>;
|
|
110
|
+
};
|
|
111
|
+
host: HostConnection;
|
|
112
|
+
t: Strings;
|
|
113
|
+
phrase: Phrases;
|
|
114
|
+
testId: string;
|
|
115
|
+
commands: KitCommand[];
|
|
116
|
+
byId: Map<string, KitCommand>;
|
|
117
|
+
enabled: (id: string) => boolean;
|
|
118
|
+
enabledNow: (id: string) => Promise<boolean>;
|
|
119
|
+
run: (id: string, params?: Record<string, unknown>) => Promise<string | null>;
|
|
120
|
+
ask: (id: string, values?: Record<string, unknown>) => void;
|
|
121
|
+
query: <R>(id: string, params?: Record<string, unknown>) => Promise<R | null>;
|
|
122
|
+
save: () => Promise<void>;
|
|
123
|
+
report: KitReport;
|
|
124
|
+
dialog: {
|
|
125
|
+
command: KitCommand;
|
|
126
|
+
values: Record<string, unknown>;
|
|
127
|
+
} | null;
|
|
128
|
+
setDialog: (command: KitCommand | null, values?: Record<string, unknown>) => void;
|
|
129
|
+
comments: ReadonlySet<string>;
|
|
130
|
+
canUndo: boolean;
|
|
131
|
+
canRedo: boolean;
|
|
132
|
+
};
|
|
133
|
+
export type KitEditor = ReturnType<typeof useKitEditorState<unknown>>;
|
|
134
|
+
/**
|
|
135
|
+
* Gives the shared controls below the editor (and the engine's tools, if it has any), and the UI
|
|
136
|
+
* configuration. The engine's tools get the configuration's check, so a tool the host denies is
|
|
137
|
+
* never active, whichever path chose it.
|
|
138
|
+
*/
|
|
139
|
+
export declare function KitEditorProvider({ editor, tools, children }: {
|
|
140
|
+
editor: KitEditor;
|
|
141
|
+
tools?: KitTools | null;
|
|
142
|
+
children: ReactNode;
|
|
143
|
+
}): import("react").JSX.Element;
|
|
144
|
+
export declare function useKitEditor(): {
|
|
145
|
+
session: {
|
|
146
|
+
run: (command: string, params?: Record<string, unknown>, damage?: RasterRect | null, options?: import(".").KitRunOptions) => Promise<string | null>;
|
|
147
|
+
editedBy: import("./useKitSession.js").KitEditedBy | null;
|
|
148
|
+
comments: ReadonlySet<string>;
|
|
149
|
+
path: string;
|
|
150
|
+
manifest: import(".").KitModuleManifest;
|
|
151
|
+
doc: import(".").KitEngine | null;
|
|
152
|
+
info: import(".").KitEngineInfo | null;
|
|
153
|
+
state: unknown;
|
|
154
|
+
change: import(".").KitChange;
|
|
155
|
+
repaints: import(".").KitRepaints;
|
|
156
|
+
dirty: boolean;
|
|
157
|
+
failure: string | null;
|
|
158
|
+
openMs: number | null;
|
|
159
|
+
saving: boolean;
|
|
160
|
+
conflict: boolean;
|
|
161
|
+
tool: <R>(name: import("./engine/kitEngine.js").KitToolMethod, args?: unknown[], settled?: boolean) => Promise<R | null>;
|
|
162
|
+
commands: () => Promise<never[] | KitCommand[]>;
|
|
163
|
+
disabledCommands: () => Promise<string[] | never[]>;
|
|
164
|
+
save: () => Promise<void>;
|
|
165
|
+
replica: {
|
|
166
|
+
version: () => Promise<ArrayBuffer>;
|
|
167
|
+
exportChanges: (since: ArrayBuffer) => Promise<{
|
|
168
|
+
changes: ArrayBuffer;
|
|
169
|
+
blobs: ArrayBuffer;
|
|
170
|
+
}>;
|
|
171
|
+
importChanges: (changes: ArrayBuffer, blobs: ArrayBuffer) => Promise<unknown>;
|
|
172
|
+
docId: () => Promise<string | null>;
|
|
173
|
+
};
|
|
174
|
+
model: {
|
|
175
|
+
describe: (schema: object | null) => Promise<Record<string, unknown>>;
|
|
176
|
+
version: () => Promise<string>;
|
|
177
|
+
changes: (since: string, schema: object | null) => Promise<import("./engine/kitEngine.js").KitModelChanges>;
|
|
178
|
+
batch: (request: Record<string, unknown>, schema: object | null) => Promise<import("@kition/kit-ui-protocol").ModelBatchResult>;
|
|
179
|
+
};
|
|
180
|
+
draft: {
|
|
181
|
+
open: () => Promise<{
|
|
182
|
+
engine: import(".").KitEngine;
|
|
183
|
+
base: ArrayBuffer;
|
|
184
|
+
}>;
|
|
185
|
+
merge: (changes: ArrayBuffer, blobs: ArrayBuffer, origin: import("@kition/kdm").Origin, schema: object | null) => Promise<import("@kition/kit-ui-protocol").DraftSummary>;
|
|
186
|
+
compare: (changes: ArrayBuffer, schema: object | null) => Promise<import("@kition/kit-ui-protocol").DraftSummary>;
|
|
187
|
+
};
|
|
188
|
+
reopen: () => void;
|
|
189
|
+
keepMine: () => Promise<void>;
|
|
190
|
+
checkFile: (isCurrent?: () => boolean) => Promise<void>;
|
|
191
|
+
holdFile: (stamp: string) => Promise<void>;
|
|
192
|
+
};
|
|
193
|
+
host: HostConnection;
|
|
194
|
+
t: Strings;
|
|
195
|
+
phrase: Phrases;
|
|
196
|
+
testId: string;
|
|
197
|
+
commands: KitCommand[];
|
|
198
|
+
byId: Map<string, KitCommand>;
|
|
199
|
+
enabled: (id: string) => boolean;
|
|
200
|
+
enabledNow: (id: string) => Promise<boolean>;
|
|
201
|
+
run: (id: string, params?: Record<string, unknown>) => Promise<string | null>;
|
|
202
|
+
ask: (id: string, values?: Record<string, unknown>) => void;
|
|
203
|
+
query: <R>(id: string, params?: Record<string, unknown>) => Promise<R | null>;
|
|
204
|
+
save: () => Promise<void>;
|
|
205
|
+
report: KitReport;
|
|
206
|
+
dialog: {
|
|
207
|
+
command: KitCommand;
|
|
208
|
+
values: Record<string, unknown>;
|
|
209
|
+
} | null;
|
|
210
|
+
setDialog: (command: KitCommand | null, values?: Record<string, unknown>) => void;
|
|
211
|
+
comments: ReadonlySet<string>;
|
|
212
|
+
canUndo: boolean;
|
|
213
|
+
canRedo: boolean;
|
|
214
|
+
};
|
|
215
|
+
/**
|
|
216
|
+
* Whether the document is read-only for this session (`document.readOnly`). The shared controls
|
|
217
|
+
* and the engine already refuse edits; a kit uses this for its own panels (a field that edits).
|
|
218
|
+
*/
|
|
219
|
+
export declare function useReadOnly(): boolean;
|
|
220
|
+
/** The engine's tools, when the editor has them. */
|
|
221
|
+
export declare function useKitTools(): {
|
|
222
|
+
tools: import(".").EngineToolInfo[];
|
|
223
|
+
active: string;
|
|
224
|
+
select: (id: string) => void;
|
|
225
|
+
setDenied: (check: (id: string) => boolean) => void;
|
|
226
|
+
refresh: () => void;
|
|
227
|
+
viewZoom: (next: number) => void;
|
|
228
|
+
typeText: (text: string) => void;
|
|
229
|
+
canvasTool: KitTool;
|
|
230
|
+
decorate: RasterDecoration | null;
|
|
231
|
+
status: string | null;
|
|
232
|
+
wantsText: boolean;
|
|
233
|
+
keyDown: (event: {
|
|
234
|
+
key: string;
|
|
235
|
+
shiftKey: boolean;
|
|
236
|
+
altKey: boolean;
|
|
237
|
+
metaKey: boolean;
|
|
238
|
+
ctrlKey: boolean;
|
|
239
|
+
}) => boolean;
|
|
240
|
+
toolForKey: (key: string, shift: boolean) => string | null;
|
|
241
|
+
} | null;
|
|
242
|
+
/**
|
|
243
|
+
* A ribbon button that runs an engine command, enabled when the engine says it can run (a kit's
|
|
244
|
+
* `disabled` only disables it further). `onRun` runs it through the kit's own entry point instead
|
|
245
|
+
* of the editor's `run` (Film's `invoke`), as `CommandItem`'s does; a command that needs values
|
|
246
|
+
* still opens its parameters dialog.
|
|
247
|
+
*/
|
|
248
|
+
export declare function CommandButton({ command, params, ask, onRun, ...props }: Omit<RibbonButtonProps, 'onClick' | 'label'> & {
|
|
249
|
+
command: string;
|
|
250
|
+
params?: Record<string, unknown>;
|
|
251
|
+
label?: string;
|
|
252
|
+
ask?: boolean;
|
|
253
|
+
onRun?: (command: string) => void;
|
|
254
|
+
}): import("react").JSX.Element | null;
|
|
255
|
+
/** A ribbon button that chooses one of the engine's tools, pressed while it is active; `testId` names it where a tool rail draws the same tool (the rail keeps `<testId>-tool-<tool>`). */
|
|
256
|
+
export declare function ToolButton({ tool, testId: ownTestId, ...props }: Omit<RibbonButtonProps, 'onClick' | 'pressed'> & {
|
|
257
|
+
tool: string;
|
|
258
|
+
testId?: string;
|
|
259
|
+
}): import("react").JSX.Element | null;
|
|
260
|
+
/** A ribbon button that opens a menu (a split button's arrow, a gallery); `primary` shows it in Single line's row (its icon alone unless `lineLabel`). */
|
|
261
|
+
export declare function RibbonMenu({ icon, label, size, children, disabled, swatch, testId, primary, lineLabel }: {
|
|
262
|
+
icon?: IconComponent;
|
|
263
|
+
label: string;
|
|
264
|
+
size?: 'large' | 'small' | 'icon';
|
|
265
|
+
children: ReactNode;
|
|
266
|
+
disabled?: boolean;
|
|
267
|
+
swatch?: string;
|
|
268
|
+
testId?: string;
|
|
269
|
+
primary?: boolean;
|
|
270
|
+
lineLabel?: boolean;
|
|
271
|
+
}): import("react").JSX.Element | null;
|
|
272
|
+
/**
|
|
273
|
+
* A menu item that runs an engine command. `shortcut` replaces the engine's own (null shows none);
|
|
274
|
+
* `checked` makes it a toggle with a check mark. `path` is the menu it is drawn under when that is
|
|
275
|
+
* not the engine's own (a catalog's): hides and disables of that menu apply too.
|
|
276
|
+
*/
|
|
277
|
+
export declare function CommandItem({ command, params, label, icon, ask, shortcut, checked, path, onRun, }: {
|
|
278
|
+
command: string;
|
|
279
|
+
params?: Record<string, unknown>;
|
|
280
|
+
label?: string;
|
|
281
|
+
icon?: IconComponent;
|
|
282
|
+
ask?: boolean;
|
|
283
|
+
shortcut?: string | null;
|
|
284
|
+
checked?: boolean;
|
|
285
|
+
path?: readonly string[];
|
|
286
|
+
/**
|
|
287
|
+
* Runs the command instead of the editor's `run` (an app's own entry point, as Film's `invoke`).
|
|
288
|
+
* A command that needs values still opens its parameters dialog.
|
|
289
|
+
*/
|
|
290
|
+
onRun?: (command: string) => void;
|
|
291
|
+
}): import("react").JSX.Element | null;
|
|
292
|
+
/**
|
|
293
|
+
* The commands under `menu` (and `extra` menus), grouped by their second menu segment. A group
|
|
294
|
+
* that is only one command named after itself (the engine's `["Insert", "Block..."]`), or any
|
|
295
|
+
* group whose name ends in an ellipsis, is not a group: its commands join one general group named
|
|
296
|
+
* after their menu (the tab), in the place the first of them came.
|
|
297
|
+
*/
|
|
298
|
+
export declare function commandGroups(commands: readonly KitCommand[], menus: readonly string[]): Map<string, {
|
|
299
|
+
path: string;
|
|
300
|
+
items: KitCommand[];
|
|
301
|
+
}>;
|
|
302
|
+
/**
|
|
303
|
+
* The engine's commands in the group at `path` (`"Insert/Illustrations"`, as `commandGroups`
|
|
304
|
+
* keys them), less any whose title is one of `titles`: the buttons a hand-made group of the same
|
|
305
|
+
* name already draws (its own "Shapes" beside the engine's).
|
|
306
|
+
*/
|
|
307
|
+
export declare function commandsOfGroup(commands: readonly KitCommand[], path: string, titles?: readonly string[]): KitCommand[];
|
|
308
|
+
/**
|
|
309
|
+
* The engine's commands of the group at `path` as ribbon buttons, for a hand-made group that
|
|
310
|
+
* takes the engine's group of the same name into itself (pair it with `CommandTab`'s `omit`).
|
|
311
|
+
* `primary` lists the commands shown in Single line's row; the row reaches this element only when
|
|
312
|
+
* `primary` is given.
|
|
313
|
+
*/
|
|
314
|
+
export declare function CommandGroupButtons({ path, titles, exclude, primary }: {
|
|
315
|
+
path: string;
|
|
316
|
+
titles?: readonly string[];
|
|
317
|
+
exclude?: readonly string[];
|
|
318
|
+
primary?: readonly string[];
|
|
319
|
+
}): import("react").JSX.Element | null;
|
|
320
|
+
/**
|
|
321
|
+
* A ribbon tab built from the engine's own command paths (`menu: [tab, group]`), for tabs the
|
|
322
|
+
* editor does not lay out by hand: every command stays reachable, and one that needs values
|
|
323
|
+
* opens its parameters dialog. `label` names a group (the engine's name by default); `omit`
|
|
324
|
+
* leaves out groups a hand-made group already shows (see `CommandGroupButtons`). `primary` lists
|
|
325
|
+
* the commands shown in Single line's row.
|
|
326
|
+
*/
|
|
327
|
+
export declare function CommandTab({ menu, extra, exclude, omit, label, primary }: {
|
|
328
|
+
menu: string;
|
|
329
|
+
extra?: string[];
|
|
330
|
+
exclude?: string[];
|
|
331
|
+
omit?: string[];
|
|
332
|
+
label?: (group: string) => string;
|
|
333
|
+
primary?: readonly string[];
|
|
334
|
+
}): import("react").JSX.Element;
|
|
335
|
+
/** The engine's top-level menus in `order` (others after), as ribbon tabs. */
|
|
336
|
+
export declare function commandMenus(commands: readonly KitCommand[], order: readonly string[]): string[];
|
|
337
|
+
/**
|
|
338
|
+
* The document area: the engine's canvas once open, why not when it failed, and the field that
|
|
339
|
+
* takes typed text for the engine's text tools (so input methods compose).
|
|
340
|
+
*/
|
|
341
|
+
export declare function KitDocumentCanvas({ canvas, viewMemory, initialArea, panBounds, framed, animated, onView, testId, tool, decorate, decorateUnder, children, }: {
|
|
342
|
+
canvas: RefObject<KitCanvasHandle | null>;
|
|
343
|
+
viewMemory?: RefObject<RasterView | null>;
|
|
344
|
+
initialArea?: RasterRect | null;
|
|
345
|
+
/** The page bounds scrolling stops at; absent for a freely pannable canvas. */
|
|
346
|
+
panBounds?: RasterRect | null;
|
|
347
|
+
framed?: boolean;
|
|
348
|
+
animated?: boolean;
|
|
349
|
+
onView?: (view: KitCanvasView, stats: RasterViewportStats | null) => void;
|
|
350
|
+
testId?: string;
|
|
351
|
+
/** The editor's own pointer tool, for engines without tools of their own (the engine's by default). */
|
|
352
|
+
tool?: KitTool;
|
|
353
|
+
/**
|
|
354
|
+
* The editor's own decoration (selection outlines, other people's selections, comment pins),
|
|
355
|
+
* drawn over the document and over the engine's overlays (its caret and selection), which it
|
|
356
|
+
* can never hide.
|
|
357
|
+
*/
|
|
358
|
+
decorate?: RasterDecoration | null;
|
|
359
|
+
/**
|
|
360
|
+
* The editor's decoration under the engine's overlays, over the document: what the engine's
|
|
361
|
+
* selection and handles must cover (layout grids, frame name labels, a pixel grid).
|
|
362
|
+
*/
|
|
363
|
+
decorateUnder?: RasterDecoration | null;
|
|
364
|
+
/** Over the canvas: an editor's in-place fields (new text). */
|
|
365
|
+
children?: ReactNode;
|
|
366
|
+
}): import("react").JSX.Element;
|
|
367
|
+
/** Whether the target takes typed text (so the editor's shortcuts leave its keys alone). */
|
|
368
|
+
export declare function isField(target: EventTarget | null): boolean;
|
|
369
|
+
export type ShellProps = {
|
|
370
|
+
status?: ReactNode;
|
|
371
|
+
statusEnd?: ReactNode;
|
|
372
|
+
/**
|
|
373
|
+
* A click on the status bar (outside its buttons), for an editor whose status bar is one click
|
|
374
|
+
* target, as a ported app's that clears its message on a click.
|
|
375
|
+
*/
|
|
376
|
+
onStatusClick?: () => void;
|
|
377
|
+
canvas?: RefObject<KitCanvasHandle | null>;
|
|
378
|
+
/** The canvas zoom, for the status bar's zoom control. */
|
|
379
|
+
zoom?: number | null;
|
|
380
|
+
/** The editor's own keys; return true when handled. */
|
|
381
|
+
onKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => boolean;
|
|
382
|
+
/**
|
|
383
|
+
* Whether the status bar is drawn (default true). Off, the whole bar goes, like a native app's
|
|
384
|
+
* View or Window toggle: `status`, the unsaved and agent-edited marks, and the zoom control;
|
|
385
|
+
* Save stays enabled while there are unsaved changes.
|
|
386
|
+
*/
|
|
387
|
+
statusBar?: boolean;
|
|
388
|
+
/**
|
|
389
|
+
* Engine commands the kit never shows (a browser cannot run them): their shortcuts run nothing,
|
|
390
|
+
* and the key goes on as if no command had it (to a tool letter; a host button's comes first).
|
|
391
|
+
*/
|
|
392
|
+
hiddenCommands?: (command: string) => boolean;
|
|
393
|
+
/**
|
|
394
|
+
* Whether the frame asks what to do when the file changed on disk while the document has unsaved
|
|
395
|
+
* edits (the session's `conflict`): keep the edits (the next save replaces the file) or load the
|
|
396
|
+
* new version. Default true; a kit that asks in its own way (a merge) turns it off. Without an
|
|
397
|
+
* answer every save is refused, so the person could not keep their edits.
|
|
398
|
+
*/
|
|
399
|
+
fileChangedBar?: boolean;
|
|
400
|
+
children: ReactNode;
|
|
401
|
+
};
|
|
402
|
+
/**
|
|
403
|
+
* Undo's and Redo's state where the frame draws them (the top bar, the Focus bar): each also
|
|
404
|
+
* follows its engine command (hidden with it by the host, disabled when it is denied), and a
|
|
405
|
+
* read-only document offers them only to a commenter (their own comments).
|
|
406
|
+
* @internal
|
|
407
|
+
*/
|
|
408
|
+
export declare function useHistoryState(): {
|
|
409
|
+
undo: {
|
|
410
|
+
hidden: boolean;
|
|
411
|
+
disabled: boolean;
|
|
412
|
+
};
|
|
413
|
+
redo: {
|
|
414
|
+
hidden: boolean;
|
|
415
|
+
disabled: boolean;
|
|
416
|
+
};
|
|
417
|
+
readOnly: boolean;
|
|
418
|
+
commenting: boolean;
|
|
419
|
+
};
|
|
420
|
+
/** The host's buttons, Undo, Redo, Ask Agent (when the host has an agent), the mode button, Save, and More (Customize). @internal */
|
|
421
|
+
export declare function DocumentActions({ before, mode }: {
|
|
422
|
+
before?: ReactNode;
|
|
423
|
+
mode?: ReactNode;
|
|
424
|
+
}): import("react").JSX.Element;
|
|
425
|
+
/** What `EditorFrame` gives the shell: its root (for the step-down's width), its modes, its density, and its own keys (Focus). @internal */
|
|
426
|
+
export type ShellFrameState = {
|
|
427
|
+
ref: RefObject<HTMLDivElement | null>;
|
|
428
|
+
mode: string;
|
|
429
|
+
chosen: string;
|
|
430
|
+
touch: boolean;
|
|
431
|
+
viewOnly: boolean;
|
|
432
|
+
keyDown: (event: KeyboardEvent<HTMLDivElement>) => boolean;
|
|
433
|
+
escape: () => boolean;
|
|
434
|
+
};
|
|
435
|
+
/**
|
|
436
|
+
* What both shells share: keys, the body, the status bar with zoom, the parameters dialog, the
|
|
437
|
+
* customize dialog and the Hide menu (when the host keeps personal hides and the kit declares its
|
|
438
|
+
* UI), and notices. Keys go,
|
|
439
|
+
* in order, to the engine's tool, the editor's own handler, the host buttons' shortcuts (so a
|
|
440
|
+
* host can bind Cmd+S), Cmd+S (unless the host denies Save), zoom, the engine's command
|
|
441
|
+
* shortcuts (except `hiddenCommands`'), and tool letters; none of them fire while typing in a field.
|
|
442
|
+
* The frame's own key (Cmd+\) comes before all of them and works in a field too. Escape in Focus
|
|
443
|
+
* comes after them: the kit's first (a tool, gesture, or selection to cancel, a field), and only
|
|
444
|
+
* an Escape nothing took (left not default-prevented) leaves Focus.
|
|
445
|
+
* @internal
|
|
446
|
+
*/
|
|
447
|
+
export declare function ShellFrame({ top, status, statusEnd, onStatusClick, canvas, zoom, onKeyDown, statusBar, hiddenCommands, fileChangedBar, frame, children }: ShellProps & {
|
|
448
|
+
top: ReactNode;
|
|
449
|
+
frame?: ShellFrameState;
|
|
450
|
+
}): import("react").JSX.Element;
|
|
451
|
+
type MenuNode = {
|
|
452
|
+
label: string;
|
|
453
|
+
commands: KitCommand[];
|
|
454
|
+
submenus: Map<string, KitCommand[]>;
|
|
455
|
+
};
|
|
456
|
+
/** The engine's commands as menus: the first menu segment, then submenus by the second, in `order`; only `visible` commands. */
|
|
457
|
+
export declare function commandMenuTree(commands: readonly KitCommand[], order: readonly string[], exclude: readonly string[], visible?: (command: KitCommand) => boolean): MenuNode[];
|
|
458
|
+
/**
|
|
459
|
+
* A submenu row (`menu:<path>`): its rows, then the host's buttons at `menu:<path>`, fly out beside
|
|
460
|
+
* it while the pointer is over it. A submenu may hold submenus of its own, to any depth. A submenu
|
|
461
|
+
* that is not a menu bar's (a panel menu's Font Size) names its own `uiId` (and `testId`), which
|
|
462
|
+
* also places the host's buttons.
|
|
463
|
+
*/
|
|
464
|
+
export declare function SubMenu({ label, path, children, uiId, testId }: {
|
|
465
|
+
label: string;
|
|
466
|
+
path: string;
|
|
467
|
+
children: ReactNode;
|
|
468
|
+
uiId?: string;
|
|
469
|
+
testId?: string;
|
|
470
|
+
}): import("react").JSX.Element;
|
|
471
|
+
/** The active tool's options under the menus: what does not fit scrolls, as the ribbon's groups do. @internal */
|
|
472
|
+
export declare function ToolOptionsBar({ children }: {
|
|
473
|
+
children: ReactNode;
|
|
474
|
+
}): import("react").JSX.Element;
|
|
475
|
+
export type RailTool = {
|
|
476
|
+
id: string;
|
|
477
|
+
label: string;
|
|
478
|
+
icon: IconComponent;
|
|
479
|
+
shortcut?: string | null;
|
|
480
|
+
group?: number;
|
|
481
|
+
section?: number;
|
|
482
|
+
};
|
|
483
|
+
/**
|
|
484
|
+
* A vertical rail of tools (a drawing app's toolbox). Tools that share a `group` share one slot,
|
|
485
|
+
* as in Illustrator and Photoshop: it shows the active one, else the one last active there, else
|
|
486
|
+
* its first tool the host allows (upstream's `slot_tool`), and its flyout of the others opens on a
|
|
487
|
+
* right-click or a long press. A slot whose tools' `section` differs from the slot before it gets a
|
|
488
|
+
* hairline divider ahead of it (today's behavior when no tool sets `section`: one section, no
|
|
489
|
+
* dividers). With `columns={2}` slots flow in two columns, a section's
|
|
490
|
+
* slots never sharing a row with another section's; with `'auto'` (upstream's own rule), the rail
|
|
491
|
+
* doubles only once one column's slots no longer fit the height its container gives it (the rail's
|
|
492
|
+
* own height would change with its content, so a kit using `'auto'` must put the rail in a row that
|
|
493
|
+
* itself has a settled height, as the app shell's body row does). With `onColumns` (and `columns`
|
|
494
|
+
* 1 or 2), a toggle heads the rail, as Photoshop's chevrons do: it asks for the other count, which
|
|
495
|
+
* the kit keeps (in its kit store, say) and passes back as `columns`; the toggle is the Kit UI
|
|
496
|
+
* element `columnsUiId` (which the kit declares), so a host hides or disables it. With
|
|
497
|
+
* `slotMemory={false}` a slot shows its active tool, else its first allowed one, never the one
|
|
498
|
+
* last active there (an editor whose upstream draws the group's first tool). `flyoutPressMs` is
|
|
499
|
+
* how long a press opens the flyout; the release of that press selects nothing.
|
|
500
|
+
*/
|
|
501
|
+
export declare function ToolRail({ tools, active, onSelect, columns, onColumns, columnsUiId, slotMemory, flyoutPressMs }: {
|
|
502
|
+
tools: readonly RailTool[];
|
|
503
|
+
active: string;
|
|
504
|
+
onSelect: (id: string) => void;
|
|
505
|
+
columns?: 1 | 2 | 'auto';
|
|
506
|
+
onColumns?: (next: 1 | 2) => void;
|
|
507
|
+
columnsUiId?: string;
|
|
508
|
+
slotMemory?: boolean;
|
|
509
|
+
flyoutPressMs?: number;
|
|
510
|
+
}): import("react").JSX.Element;
|
|
511
|
+
/** The engine's own tools (engine-tools capability) on a rail, translated, minus `hidden`. */
|
|
512
|
+
export declare function EngineToolRail({ hidden }: {
|
|
513
|
+
hidden?: readonly string[];
|
|
514
|
+
}): import("react").JSX.Element | null;
|
|
515
|
+
/** A titled, collapsible section of a side panel (Layers, Properties, Swatches). With an `id` (`panel:<name>`) it follows the UI configuration. */
|
|
516
|
+
export declare function PanelSection({ id, title, children, defaultOpen, actions, testId }: {
|
|
517
|
+
id?: string;
|
|
518
|
+
title: string;
|
|
519
|
+
children: ReactNode;
|
|
520
|
+
defaultOpen?: boolean;
|
|
521
|
+
actions?: ReactNode;
|
|
522
|
+
testId?: string;
|
|
523
|
+
}): import("react").JSX.Element | null;
|
|
524
|
+
/** Bytes as base64, for commands that take a file's contents (`insert.picture {data}`). */
|
|
525
|
+
export declare function base64(bytes: ArrayBuffer | Uint8Array): string;
|
|
526
|
+
export declare const PICTURE_TYPES: string[];
|
|
527
|
+
/**
|
|
528
|
+
* Choosing a workspace file through the host (`host/pick`, then `host/read`): `can` is whether
|
|
529
|
+
* the host offers it; `pick` answers the file, or null when the person cancels.
|
|
530
|
+
*/
|
|
531
|
+
export declare function useHostPick(): {
|
|
532
|
+
can: boolean;
|
|
533
|
+
pick: (purpose: string, accept: string[]) => Promise<{
|
|
534
|
+
path: string;
|
|
535
|
+
name: string;
|
|
536
|
+
bytes: ArrayBuffer;
|
|
537
|
+
} | null>;
|
|
538
|
+
};
|
|
539
|
+
/**
|
|
540
|
+
* A query's answer (a command that reads without editing), asked again after every change:
|
|
541
|
+
* `format.state` for the ribbon's toggles, `view.state` for the view's.
|
|
542
|
+
*/
|
|
543
|
+
export declare function useEngineQuery<R>(id: string, params?: Record<string, unknown>, extra?: unknown): R | null;
|
|
544
|
+
export {};
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { type ReactNode, type Ref, type RefObject } from 'react';
|
|
2
|
+
import type { KitEngine } from './kitEngine.js';
|
|
3
|
+
import { type KitTool } from './kitTools.js';
|
|
4
|
+
import { type RasterDecoration, type RasterRect, type RasterView, type RasterViewportStats } from './rasterViewport.js';
|
|
5
|
+
import type { KitChange, KitRepaint } from './useKitDocument.js';
|
|
6
|
+
/** The canvas's view (its zoom and the document point at its top-left) and its size in CSS pixels. */
|
|
7
|
+
export type KitCanvasView = RasterView & {
|
|
8
|
+
width: number;
|
|
9
|
+
height: number;
|
|
10
|
+
};
|
|
11
|
+
export type KitCanvasHandle = {
|
|
12
|
+
/** The current view and the canvas's size, or null before the canvas is laid out. */
|
|
13
|
+
view: () => KitCanvasView | null;
|
|
14
|
+
fit: () => void;
|
|
15
|
+
/** Fits an area of the document (a page, a spread) in view. */
|
|
16
|
+
show: (area: RasterRect) => void;
|
|
17
|
+
zoomTo: (zoom: number) => void;
|
|
18
|
+
zoomBy: (factor: number) => void;
|
|
19
|
+
/** Scrolls so document point (`x`, `y`) is at the top-left, keeping the zoom. */
|
|
20
|
+
panTo: (x: number, y: number) => void;
|
|
21
|
+
/** Paints the same live document again, preserving unsaved edits and the current view. */
|
|
22
|
+
retryRender: () => Promise<boolean>;
|
|
23
|
+
};
|
|
24
|
+
type KitCanvasProps = {
|
|
25
|
+
doc: KitEngine;
|
|
26
|
+
/** Moves with every document change; the canvas repaints what it names. */
|
|
27
|
+
change: KitChange;
|
|
28
|
+
/** Moves with each repaint asked for without a document change (a run with `refresh: 'repaint'`). */
|
|
29
|
+
repaint?: KitRepaint;
|
|
30
|
+
tool: KitTool;
|
|
31
|
+
/** Every change of the view (a scroll, a zoom, the canvas resized), with the canvas's size. */
|
|
32
|
+
onView: (view: KitCanvasView, stats: RasterViewportStats | null) => void;
|
|
33
|
+
onRender?: (error: unknown | null) => void;
|
|
34
|
+
/** The last view, kept when the document is replaced by a newer version of the file. */
|
|
35
|
+
viewMemory: RefObject<RasterView | null>;
|
|
36
|
+
/** Drawn over the document on every frame; `animated` redraws it continuously (marching ants). */
|
|
37
|
+
decorate?: RasterDecoration | null;
|
|
38
|
+
animated?: boolean;
|
|
39
|
+
/** The area the first view fits (a layout's first spread); the whole document by default. */
|
|
40
|
+
initialArea?: RasterRect | null;
|
|
41
|
+
/** The document bounds scrolling stops at; absent for a freely pannable canvas. */
|
|
42
|
+
panBounds?: RasterRect | null;
|
|
43
|
+
/** Whether holding Space pans (on by default); a player uses Space for play and pause. */
|
|
44
|
+
spacePans?: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* A page shadow and transparency checks under the document (on by default). Off for an engine
|
|
47
|
+
* that paints its own canvas around the document (slides on a pasteboard).
|
|
48
|
+
*/
|
|
49
|
+
framed?: boolean;
|
|
50
|
+
/** HTML laid over the canvas, for example an inline text field. */
|
|
51
|
+
children?: ReactNode;
|
|
52
|
+
ref?: Ref<KitCanvasHandle>;
|
|
53
|
+
};
|
|
54
|
+
/**
|
|
55
|
+
* A pointer's pressure, 0 to 1. Only a pen has one: a mouse, a finger, or an unknown device is 1
|
|
56
|
+
* (browsers report 0.5 for a pressed mouse button, which would halve a pressure-sized brush). A
|
|
57
|
+
* pen sample that reports 0 keeps `previous`, the stroke's last pressure (1 at its first sample).
|
|
58
|
+
*/
|
|
59
|
+
export declare function pressureOf(event: {
|
|
60
|
+
pressure: number;
|
|
61
|
+
pointerType?: string;
|
|
62
|
+
}, previous?: number): number;
|
|
63
|
+
/**
|
|
64
|
+
* A kit document on a canvas, with Kition's pointer handling: the active
|
|
65
|
+
* tool gets gestures in document pixels; Space, the middle button, and the
|
|
66
|
+
* Hand tool pan; the wheel pans, and zooms with Cmd or Ctrl (and pinch). Escape drops a held
|
|
67
|
+
* gesture.
|
|
68
|
+
*/
|
|
69
|
+
export declare function KitCanvas({ doc, change, repaint, tool, onView, onRender, viewMemory, initialArea, panBounds, decorate, animated, spacePans, framed, children, ref }: KitCanvasProps): import("react").JSX.Element;
|
|
70
|
+
export {};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { KitEngine } from './kitEngine.js';
|
|
2
|
+
import type { KitHost } from './kitHost.js';
|
|
3
|
+
import type { KitModuleManifest } from './kitModule.js';
|
|
4
|
+
/**
|
|
5
|
+
* Makes a new file with a kit's SDK: an empty document of the given size,
|
|
6
|
+
* optionally prepared with commands (import a clip, build a sequence from it),
|
|
7
|
+
* then saved and written to `path` through the host. No kit process is involved.
|
|
8
|
+
*/
|
|
9
|
+
export declare function createKitFile(host: KitHost, manifest: KitModuleManifest, path: string, size: {
|
|
10
|
+
width: number;
|
|
11
|
+
height: number;
|
|
12
|
+
}, prepare?: (engine: KitEngine) => Promise<void>): Promise<void>;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Stacking canvas decorations: the engine's overlays (its caret, its selection, a tool's
|
|
3
|
+
* preview) under a kit's own decoration, so a kit's decoration (comment pins, other people's
|
|
4
|
+
* selections, markers) adds to them and never hides them.
|
|
5
|
+
*/
|
|
6
|
+
import type { RasterDecoration } from './rasterViewport.js';
|
|
7
|
+
/**
|
|
8
|
+
* `draw`, made to draw nothing while `stackDecorations` has already drawn it under the
|
|
9
|
+
* decoration being drawn now: a kit's decoration that still draws the engine's overlays itself
|
|
10
|
+
* (as kits had to before the canvas stacked them) does not draw them twice.
|
|
11
|
+
*/
|
|
12
|
+
export declare function drawnOnce(draw: RasterDecoration): RasterDecoration;
|
|
13
|
+
/** `under` then `over`, each on its own canvas state (either may be absent). */
|
|
14
|
+
export declare function stackDecorations(under: RasterDecoration | null | undefined, over: RasterDecoration | null | undefined): RasterDecoration | null;
|