@kition/kit-editor 0.0.0-stage → 0.1.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.
Files changed (66) hide show
  1. package/README.md +103 -2
  2. package/dist/LICENSE +177 -0
  3. package/dist/assets/kitEngine.worker-9PIHJagj.js +13020 -0
  4. package/dist/chunks/workspaceTree-CpJ2i9hy.js +23 -0
  5. package/dist/index.js +6434 -0
  6. package/dist/styles.css +807 -0
  7. package/dist/types/src/CommandDialog.d.ts +22 -0
  8. package/dist/types/src/CommentsPanel.d.ts +45 -0
  9. package/dist/types/src/CustomizeDialog.d.ts +32 -0
  10. package/dist/types/src/HostButtons.d.ts +11 -0
  11. package/dist/types/src/RenderFailure.d.ts +7 -0
  12. package/dist/types/src/TextSink.d.ts +6 -0
  13. package/dist/types/src/brand.d.ts +2 -0
  14. package/dist/types/src/catalogMenus.d.ts +27 -0
  15. package/dist/types/src/chart.d.ts +138 -0
  16. package/dist/types/src/conflicts.d.ts +12 -0
  17. package/dist/types/src/drawing.d.ts +83 -0
  18. package/dist/types/src/editor.d.ts +544 -0
  19. package/dist/types/src/engine/KitCanvas.d.ts +70 -0
  20. package/dist/types/src/engine/createKitFile.d.ts +12 -0
  21. package/dist/types/src/engine/decorations.d.ts +14 -0
  22. package/dist/types/src/engine/engineOverlays.d.ts +197 -0
  23. package/dist/types/src/engine/engineTools.d.ts +116 -0
  24. package/dist/types/src/engine/kitDraft.d.ts +70 -0
  25. package/dist/types/src/engine/kitEngine.d.ts +370 -0
  26. package/dist/types/src/engine/kitEngine.worker.d.ts +30 -0
  27. package/dist/types/src/engine/kitHost.d.ts +41 -0
  28. package/dist/types/src/engine/kitModel.d.ts +32 -0
  29. package/dist/types/src/engine/kitModelRunner.d.ts +93 -0
  30. package/dist/types/src/engine/kitModule.d.ts +173 -0
  31. package/dist/types/src/engine/kitShortcuts.d.ts +32 -0
  32. package/dist/types/src/engine/kitTools.d.ts +79 -0
  33. package/dist/types/src/engine/lentFiles.d.ts +29 -0
  34. package/dist/types/src/engine/rasterViewport.d.ts +178 -0
  35. package/dist/types/src/engine/readOnly.d.ts +78 -0
  36. package/dist/types/src/engine/refusal.d.ts +39 -0
  37. package/dist/types/src/engine/replica.d.ts +23 -0
  38. package/dist/types/src/engine/useKitDocument.d.ts +154 -0
  39. package/dist/types/src/engine/workerRelay.d.ts +62 -0
  40. package/dist/types/src/files.d.ts +74 -0
  41. package/dist/types/src/frame/EditorFrame.d.ts +74 -0
  42. package/dist/types/src/frame/FocusBar.d.ts +10 -0
  43. package/dist/types/src/frame/MenuNodes.d.ts +20 -0
  44. package/dist/types/src/frame/MenuRibbon.d.ts +8 -0
  45. package/dist/types/src/frame/ModeButton.d.ts +7 -0
  46. package/dist/types/src/frame/menus.d.ts +64 -0
  47. package/dist/types/src/frame/modes.d.ts +51 -0
  48. package/dist/types/src/frame/useFrameLayout.d.ts +34 -0
  49. package/dist/types/src/host.d.ts +127 -0
  50. package/dist/types/src/index.d.ts +84 -0
  51. package/dist/types/src/ink.d.ts +26 -0
  52. package/dist/types/src/lease.d.ts +53 -0
  53. package/dist/types/src/oneInFlight.d.ts +7 -0
  54. package/dist/types/src/phrases.d.ts +25 -0
  55. package/dist/types/src/presence.d.ts +79 -0
  56. package/dist/types/src/strings.d.ts +6 -0
  57. package/dist/types/src/toolIcons.d.ts +32 -0
  58. package/dist/types/src/uiCatalog.d.ts +59 -0
  59. package/dist/types/src/uiConfig.d.ts +53 -0
  60. package/dist/types/src/uiContext.d.ts +65 -0
  61. package/dist/types/src/uiStore.d.ts +20 -0
  62. package/dist/types/src/useCommentAnchors.d.ts +29 -0
  63. package/dist/types/src/useKitSession.d.ts +115 -0
  64. package/dist/types/src/workspaceTree.d.ts +5 -0
  65. package/dist/workspaceTree.js +1 -0
  66. 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;