@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,154 @@
|
|
|
1
|
+
import { KitEngine, type KitAgentStep, type KitEngineInfo, type KitToolMethod } from './kitEngine.js';
|
|
2
|
+
import type { KitModuleManifest } from './kitModule.js';
|
|
3
|
+
import type { KitHost } from './kitHost.js';
|
|
4
|
+
import type { RasterRect } from './rasterViewport.js';
|
|
5
|
+
import type { Origin } from '@kition/kdm';
|
|
6
|
+
/** One edit: the canvas repaints `damage`, or everything when it is null. */
|
|
7
|
+
export type KitChange = {
|
|
8
|
+
revision: number;
|
|
9
|
+
damage: RasterRect | null;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* What a command refreshes once it ran:
|
|
13
|
+
* - `all` (the default): the editor's state (`describe`), the engine info, and the change counter,
|
|
14
|
+
* which repaints the canvas and re-asks the editor's queries;
|
|
15
|
+
* - `repaint`: only the canvas repaints (`repaints`), for a command that changes what the document
|
|
16
|
+
* shows but nothing the editor reads (a player's playhead): no describe, no queries, no host
|
|
17
|
+
* notification, and no render of the editor;
|
|
18
|
+
* - `none`: nothing, for a command whose effect the editor follows itself.
|
|
19
|
+
*/
|
|
20
|
+
export type KitRefresh = 'all' | 'repaint' | 'none';
|
|
21
|
+
export type KitRunOptions = {
|
|
22
|
+
refresh?: KitRefresh;
|
|
23
|
+
/**
|
|
24
|
+
* With `refresh: 'all'`, a command that moved neither the engine's revision nor its `inspect()`
|
|
25
|
+
* (a selection the picture does not show) refreshes the editor without repainting the canvas,
|
|
26
|
+
* as an engine tool call that changed nothing does. A command that changed what `inspect()`
|
|
27
|
+
* says (a playhead) still repaints.
|
|
28
|
+
*/
|
|
29
|
+
skipUnchangedPaint?: boolean;
|
|
30
|
+
/**
|
|
31
|
+
* The origin the command runs as (KitModel M11): `ai/run` runs its
|
|
32
|
+
* steps as the agent, so they are the agent's undo steps and the person's Undo keeps them
|
|
33
|
+
* (M12a). An engine that does not run commands as an origin (no `executeAs`) runs them as the
|
|
34
|
+
* host's person. Unset: the host's person.
|
|
35
|
+
*/
|
|
36
|
+
origin?: Origin;
|
|
37
|
+
/**
|
|
38
|
+
* An agent step in the agent's own editor state (`KitAgentStep`, C3b): the person's selection,
|
|
39
|
+
* part and time stay as they are, and `agent.state` follows the agent's.
|
|
40
|
+
*/
|
|
41
|
+
agent?: KitAgentStep;
|
|
42
|
+
};
|
|
43
|
+
/** The area an engine tool's answer says its event changed (`damage`), or null: repaint everything. */
|
|
44
|
+
export declare function toolDamage(answer: unknown): RasterRect | null;
|
|
45
|
+
/** A canvas repaint asked for without a document change: `tick` moves with each, `damage` limits it. */
|
|
46
|
+
export type KitRepaint = {
|
|
47
|
+
tick: number;
|
|
48
|
+
damage: RasterRect | null;
|
|
49
|
+
};
|
|
50
|
+
/** A store of `KitRepaint`s the canvas subscribes to, so a repaint renders nothing else. */
|
|
51
|
+
export type KitRepaints = {
|
|
52
|
+
get: () => KitRepaint;
|
|
53
|
+
subscribe: (listener: () => void) => () => void;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* Runs `work` (a command) after the engine tool events still waiting on the page: see
|
|
57
|
+
* `orderCommands`.
|
|
58
|
+
*/
|
|
59
|
+
export type CommandOrder = <T>(work: () => Promise<T>) => Promise<T>;
|
|
60
|
+
/**
|
|
61
|
+
* Lets the engine tools driven by `tool` (a document's `tool` call) order that document's
|
|
62
|
+
* commands: a shortcut pressed right after fast keys (Shift+Arrow) must run after them, but the
|
|
63
|
+
* tools send their events one at a time and the others wait on the page. Answers how to stop.
|
|
64
|
+
*/
|
|
65
|
+
export declare function orderCommands(tool: object, order: CommandOrder): () => void;
|
|
66
|
+
/** How a document follows its file and its stored replica (`useKitDocument`). */
|
|
67
|
+
export type KitDocumentOptions = {
|
|
68
|
+
readOnly?: boolean;
|
|
69
|
+
canComment?: boolean;
|
|
70
|
+
/**
|
|
71
|
+
* The kit's engine merges what the file holds into an older stored replica when it opens (as
|
|
72
|
+
* the note's does): the stored replica opens whatever the file's stamp, so a document changed
|
|
73
|
+
* on disk while it was closed keeps its comments and history. Off: a stored replica opens only
|
|
74
|
+
* with the file it was saved with.
|
|
75
|
+
*/
|
|
76
|
+
replicaMergesFile?: boolean;
|
|
77
|
+
/**
|
|
78
|
+
* The file changed on disk while the document has no unsaved edits. Answers `true` when the kit
|
|
79
|
+
* took the change in itself (the open engine merged the file, keeping its undo history and the
|
|
80
|
+
* editor's scroll position; the engine's `info` is read again after); `false`, or a failure, reopens the document from the file as
|
|
81
|
+
* without it. Not asked while there are unsaved edits, which raise `conflict`.
|
|
82
|
+
*/
|
|
83
|
+
followFile?: (engine: KitEngine, stamp: string) => boolean | Promise<boolean>;
|
|
84
|
+
};
|
|
85
|
+
/**
|
|
86
|
+
* A save refused because the file changed on disk since the document read or wrote it: writing
|
|
87
|
+
* would replace that change. The document raises `conflict`; the person merges the change or keeps
|
|
88
|
+
* theirs (`keepMine`), and saves again.
|
|
89
|
+
*/
|
|
90
|
+
export declare class FileChangedError extends Error {
|
|
91
|
+
constructor(path: string);
|
|
92
|
+
}
|
|
93
|
+
export declare function isFileChangedError(error: unknown): error is FileChangedError;
|
|
94
|
+
/**
|
|
95
|
+
* One workspace file opened in a kit's in-page engine: starts the engine
|
|
96
|
+
* worker with the file's bytes, runs commands, and saves the file back in
|
|
97
|
+
* place. `change` moves with every edit so the canvas knows what to repaint.
|
|
98
|
+
* While the tab is active it follows the file: when the agent saves a new
|
|
99
|
+
* version the document reloads, unless there are unsaved edits, which raise
|
|
100
|
+
* `conflict`. `describe` turns the engine's `inspect()` JSON into what the
|
|
101
|
+
* kit's editor shows; `host` reads and writes the file, and keeps its replica when it can
|
|
102
|
+
* (`replicaRead`, `replicaWrite`): the document then opens with the replica saved with the file.
|
|
103
|
+
* `options.readOnly` opens it for viewing: the engine refuses edits and `save` refuses to write;
|
|
104
|
+
* `options.canComment` (a commenter) lets the manifest's `commentCommands` through all the same.
|
|
105
|
+
* See `KitDocumentOptions` for the rest.
|
|
106
|
+
*/
|
|
107
|
+
export declare function useKitDocument<T>(host: KitHost, manifest: KitModuleManifest, path: string, active: boolean, describe: (info: KitEngineInfo) => T, options?: KitDocumentOptions): {
|
|
108
|
+
path: string;
|
|
109
|
+
manifest: KitModuleManifest;
|
|
110
|
+
doc: KitEngine | null;
|
|
111
|
+
info: KitEngineInfo | null;
|
|
112
|
+
state: T | null;
|
|
113
|
+
change: KitChange;
|
|
114
|
+
repaints: KitRepaints;
|
|
115
|
+
dirty: boolean;
|
|
116
|
+
failure: string | null;
|
|
117
|
+
openMs: number | null;
|
|
118
|
+
saving: boolean;
|
|
119
|
+
conflict: boolean;
|
|
120
|
+
run: (command: string, params?: Record<string, unknown>, damage?: RasterRect | null, options?: KitRunOptions) => Promise<string | null>;
|
|
121
|
+
tool: <R>(name: KitToolMethod, args?: unknown[], settled?: boolean) => Promise<R | null>;
|
|
122
|
+
commands: () => Promise<never[] | import("./kitModule.js").KitCommand[]>;
|
|
123
|
+
disabledCommands: () => Promise<string[] | never[]>;
|
|
124
|
+
save: () => Promise<void>;
|
|
125
|
+
replica: {
|
|
126
|
+
version: () => Promise<ArrayBuffer>;
|
|
127
|
+
exportChanges: (since: ArrayBuffer) => Promise<{
|
|
128
|
+
changes: ArrayBuffer;
|
|
129
|
+
blobs: ArrayBuffer;
|
|
130
|
+
}>;
|
|
131
|
+
importChanges: (changes: ArrayBuffer, blobs: ArrayBuffer) => Promise<unknown>;
|
|
132
|
+
docId: () => Promise<string | null>;
|
|
133
|
+
};
|
|
134
|
+
model: {
|
|
135
|
+
describe: (schema: object | null) => Promise<Record<string, unknown>>;
|
|
136
|
+
/** The replica's version (C3b), after the commands still on their way. */
|
|
137
|
+
version: () => Promise<string>;
|
|
138
|
+
/** What changed since the version `since`, after the commands still on their way (C3b). */
|
|
139
|
+
changes: (since: string, schema: object | null) => Promise<import("./kitEngine.js").KitModelChanges>;
|
|
140
|
+
batch: (request: Record<string, unknown>, schema: object | null) => Promise<import("@kition/kit-ui-protocol").ModelBatchResult>;
|
|
141
|
+
};
|
|
142
|
+
draft: {
|
|
143
|
+
open: () => Promise<{
|
|
144
|
+
engine: KitEngine;
|
|
145
|
+
base: ArrayBuffer;
|
|
146
|
+
}>;
|
|
147
|
+
merge: (changes: ArrayBuffer, blobs: ArrayBuffer, origin: Origin, schema: object | null) => Promise<import("@kition/kit-ui-protocol").DraftSummary>;
|
|
148
|
+
compare: (changes: ArrayBuffer, schema: object | null) => Promise<import("@kition/kit-ui-protocol").DraftSummary>;
|
|
149
|
+
};
|
|
150
|
+
reopen: () => void;
|
|
151
|
+
keepMine: () => Promise<void>;
|
|
152
|
+
checkFile: (isCurrent?: () => boolean) => Promise<void>;
|
|
153
|
+
holdFile: (stamp: string) => Promise<void>;
|
|
154
|
+
};
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The relay between a kit editor's page replica and its engine worker's replica. A kit whose
|
|
3
|
+
* editor edits a KDM replica in the page (typing never waits for the worker) keeps it in step with
|
|
4
|
+
* the worker's, which the host saves, co-edits through, and runs agents, comments, and scripts on.
|
|
5
|
+
*/
|
|
6
|
+
import type { Replica } from '@kition/kdm';
|
|
7
|
+
/** The engine worker's replica, as the document session exposes it (`useKitSession().replica`). */
|
|
8
|
+
export type EngineReplica = {
|
|
9
|
+
exportChanges(since: ArrayBuffer): Promise<{
|
|
10
|
+
changes: ArrayBuffer;
|
|
11
|
+
blobs: ArrayBuffer;
|
|
12
|
+
}>;
|
|
13
|
+
importChanges(changes: ArrayBuffer, blobs: ArrayBuffer): Promise<unknown>;
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* The page side of a relay when it is more than a replica: a store whose replica may be replaced
|
|
17
|
+
* (a pull that finds another replica than it started with drops what it fetched), or that applies
|
|
18
|
+
* the worker's changes itself so it can refresh its own view.
|
|
19
|
+
*/
|
|
20
|
+
export type WorkerRelayPage = {
|
|
21
|
+
/** The page's replica now. */
|
|
22
|
+
replica(): Replica;
|
|
23
|
+
/** Applies the worker's changes to the page's replica (default: `replica().importChanges`). */
|
|
24
|
+
importChanges?(changes: Uint8Array): void;
|
|
25
|
+
};
|
|
26
|
+
export type WorkerRelayOptions = {
|
|
27
|
+
/** Called with an exchange's error; the relay goes on with the next one. Default: `console.error`. */
|
|
28
|
+
report?: (error: unknown) => void;
|
|
29
|
+
/** Called after changes from the worker reached the page's replica. */
|
|
30
|
+
pulled?: () => void;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* Keeps the page's replica and the engine worker's replica of one document in step. Both are KDM
|
|
34
|
+
* replicas with their own actors, so each takes the other's changes as it would a collaborator's:
|
|
35
|
+
* the page's edits go to the worker (`push`, after each local transaction), and whatever the
|
|
36
|
+
* worker took from elsewhere (engine commands, co-editors, agents, external file merges) comes to
|
|
37
|
+
* the page (`pull`, when the session reports a change). Exchanges run one at a time, in order.
|
|
38
|
+
*
|
|
39
|
+
* A pull reads the page's version only after the worker answered: the person may type while it
|
|
40
|
+
* waits, and those edits are not the worker's yet (an edit typed during a pull used to be taken as
|
|
41
|
+
* the worker's and never sent; WebKit lost it every time).
|
|
42
|
+
*/
|
|
43
|
+
export declare class WorkerRelay {
|
|
44
|
+
private readonly engine;
|
|
45
|
+
private queue;
|
|
46
|
+
/** The page's changes the worker has, as far as the page knows. */
|
|
47
|
+
private pushed;
|
|
48
|
+
private closed;
|
|
49
|
+
private readonly page;
|
|
50
|
+
private readonly report;
|
|
51
|
+
private readonly pulled;
|
|
52
|
+
constructor(page: Replica | WorkerRelayPage, engine: EngineReplica, options?: WorkerRelayOptions);
|
|
53
|
+
/** Sends the page's edits the worker does not have yet. */
|
|
54
|
+
push(): void;
|
|
55
|
+
/** Takes the worker's changes the page does not have yet. */
|
|
56
|
+
pull(): void;
|
|
57
|
+
/** Stops the relay: exchanges not started yet are dropped. */
|
|
58
|
+
close(): void;
|
|
59
|
+
/** Waits for the exchanges asked for so far. */
|
|
60
|
+
settled(): Promise<void>;
|
|
61
|
+
private enqueue;
|
|
62
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The kit's side of KitFiles 1.0 (Kition platform `docs/platform/sets/files.md`; Kit UI protocol section 7g):
|
|
3
|
+
* files beyond the document, through the handles the host grants. The kit never names a path: it
|
|
4
|
+
* asks the host to pick or create a file, and reads and writes the handle it answers.
|
|
5
|
+
*/
|
|
6
|
+
import type { KitFileStat, KitFilesPickParams, KitSidePeer } from '@kition/kit-ui-protocol';
|
|
7
|
+
/** Bytes per `files/write` chunk: bounded memory on both sides, under the headless binding's 8 MiB. */
|
|
8
|
+
export declare const FILE_CHUNK_BYTES: number;
|
|
9
|
+
/** A file an engine command produced (standard E16): the binding takes its bytes with `takeOutput(id)`. */
|
|
10
|
+
export type KitEngineOutput = {
|
|
11
|
+
id: string;
|
|
12
|
+
suggestedName: string;
|
|
13
|
+
mime?: string;
|
|
14
|
+
};
|
|
15
|
+
export type KitFilesClient = {
|
|
16
|
+
/** The host serves `files` (create, read, write, …); hide what needs it otherwise (UI-F3). */
|
|
17
|
+
served: boolean;
|
|
18
|
+
/** The host shows a picker (`files-pick`). */
|
|
19
|
+
canPick: boolean;
|
|
20
|
+
/** The host prints (`print`). */
|
|
21
|
+
canPrint: boolean;
|
|
22
|
+
/** Shows the host's picker; send it only from a click or key handler (FA6). Empty when the person cancels. */
|
|
23
|
+
pick: (params: KitFilesPickParams) => Promise<KitFileStat[]>;
|
|
24
|
+
/** A new file beside the document, or in a folder handle with right `create`; the host picks an unused name (FA7). */
|
|
25
|
+
create: (suggestedName: string, options?: {
|
|
26
|
+
mime?: string;
|
|
27
|
+
folder?: string;
|
|
28
|
+
}) => Promise<KitFileStat>;
|
|
29
|
+
stat: (handle: string) => Promise<KitFileStat>;
|
|
30
|
+
/** One ranged read; the host may answer fewer bytes than asked. */
|
|
31
|
+
read: (handle: string, range?: {
|
|
32
|
+
offset?: number;
|
|
33
|
+
length?: number;
|
|
34
|
+
}) => Promise<{
|
|
35
|
+
bytes: ArrayBuffer;
|
|
36
|
+
version: string;
|
|
37
|
+
size: number;
|
|
38
|
+
}>;
|
|
39
|
+
/** The whole file, read on until its size. */
|
|
40
|
+
readAll: (handle: string) => Promise<{
|
|
41
|
+
bytes: Uint8Array;
|
|
42
|
+
version: string;
|
|
43
|
+
}>;
|
|
44
|
+
list: (folder: string) => Promise<KitFileStat[]>;
|
|
45
|
+
/**
|
|
46
|
+
* Writes `bytes` to a handle in staged chunks and commits them (FA9); answers the new version.
|
|
47
|
+
* Replacing an existing file (right `write`) needs the version it replaces (`expected`).
|
|
48
|
+
*/
|
|
49
|
+
write: (handle: string, bytes: Uint8Array, options?: {
|
|
50
|
+
expected?: string;
|
|
51
|
+
chunkBytes?: number;
|
|
52
|
+
}) => Promise<string>;
|
|
53
|
+
release: (handles: string[]) => Promise<void>;
|
|
54
|
+
/** Prints a PDF through the system's dialog (FA11), from a gesture; answers whether the person printed. */
|
|
55
|
+
print: (source: {
|
|
56
|
+
bytes: Uint8Array;
|
|
57
|
+
title: string;
|
|
58
|
+
} | {
|
|
59
|
+
handle: string;
|
|
60
|
+
title: string;
|
|
61
|
+
}) => Promise<boolean>;
|
|
62
|
+
/**
|
|
63
|
+
* Writes an engine command's outputs (E16) to handles: the one `targets` names for an output, or a
|
|
64
|
+
* new file `create` makes (in `folder` when given). Answers each written file's stat.
|
|
65
|
+
*/
|
|
66
|
+
writeOutputs: (outputs: KitEngineOutput[], takeOutput: (id: string) => Uint8Array | Promise<Uint8Array>, options?: {
|
|
67
|
+
targets?: Record<string, string>;
|
|
68
|
+
folder?: string;
|
|
69
|
+
}) => Promise<KitFileStat[]>;
|
|
70
|
+
/** Hears `files/revoked`: the host revoked handles, or they expired (FA4). Answers an unsubscribe. */
|
|
71
|
+
onRevoked: (listener: (handles: string[]) => void) => () => void;
|
|
72
|
+
};
|
|
73
|
+
/** The `files/*` client on a kit's connection; `capabilities` are the host's (`ui/initialize`). */
|
|
74
|
+
export declare function createFilesClient(peer: KitSidePeer, capabilities: readonly string[]): KitFilesClient;
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The frame every kit editor draws: the top bar (the kit's tabs, then the document actions and
|
|
3
|
+
* the display mode button), the command area of the display mode (none in Menus, one row in
|
|
4
|
+
* Single line, the ribbon in Classic), the active tool's options, the tool rail, side panels, the
|
|
5
|
+
* body, and the status bar. Focus hides all of it but a floating bar. The chosen mode is kept per
|
|
6
|
+
* kit, a host restricts or presets it (`ui.modes`), a mode that does not fit steps down, a coarse
|
|
7
|
+
* pointer sizes it for touch, and a read-only document shows only its viewing tabs. A Classic
|
|
8
|
+
* ribbon gives way before the frame steps down: large buttons draw small, then buttons draw their
|
|
9
|
+
* icons alone, then groups collapse to one button each from the end (`ribbonFitAt`).
|
|
10
|
+
*/
|
|
11
|
+
import { type ReactNode } from 'react';
|
|
12
|
+
import { type ShellProps } from '../editor.js';
|
|
13
|
+
import { type RibbonFit } from '@kition/tessera-ui';
|
|
14
|
+
import { type FocusTool } from './FocusBar.js';
|
|
15
|
+
import { type FrameTab } from './menus.js';
|
|
16
|
+
import type { DisplayMode } from './modes.js';
|
|
17
|
+
import { type DisplayModeState } from './useFrameLayout.js';
|
|
18
|
+
/** The display mode the frame shows (after stepping down, or `focus`); `null` outside an `EditorFrame`. */
|
|
19
|
+
export declare function useFrameMode(): DisplayMode | null;
|
|
20
|
+
/**
|
|
21
|
+
* The frame's display mode controls, for a kit's own command that changes the mode (a ported
|
|
22
|
+
* app's Show/Hide UI enters Focus with `toggleFocus`); `null` outside an `EditorFrame`.
|
|
23
|
+
*/
|
|
24
|
+
export declare function useFrameDisplay(): DisplayModeState | null;
|
|
25
|
+
/**
|
|
26
|
+
* A kit's own bar (a formula bar, sheet tabs, a notes pane, a command line), anywhere in the
|
|
27
|
+
* frame's tree: drawn in every mode but Focus, which shows the canvas and its floating bar only.
|
|
28
|
+
*/
|
|
29
|
+
export declare function FrameChrome({ children }: {
|
|
30
|
+
children: ReactNode;
|
|
31
|
+
}): import("react").JSX.Element | null;
|
|
32
|
+
/**
|
|
33
|
+
* Kits should memoize `tabs` (and the `hidden` rules inside menu tabs): a new array or function
|
|
34
|
+
* on every render rebuilds the frame's menus and generated ribbons each time.
|
|
35
|
+
*/
|
|
36
|
+
export type EditorFrameProps = Omit<ShellProps, 'children'> & {
|
|
37
|
+
/** The kit's command areas in order (File, Home, Insert, …, or a menu bar's menus); memoize it. */
|
|
38
|
+
tabs: readonly FrameTab[];
|
|
39
|
+
/** The selected tab, for a kit that chooses it itself (context tabs); with `onTab`. */
|
|
40
|
+
tab?: string;
|
|
41
|
+
onTab?: (id: string) => void;
|
|
42
|
+
/** The tab selected first when the kit does not choose (`home`); else the first. */
|
|
43
|
+
defaultTab?: string;
|
|
44
|
+
/** Before the tabs: the document's name in an editor without tabs. */
|
|
45
|
+
title?: ReactNode;
|
|
46
|
+
/** The kit's own buttons before the document actions (Render, Comments). */
|
|
47
|
+
actions?: ReactNode;
|
|
48
|
+
/** The active tool's options, under the command area. */
|
|
49
|
+
options?: ReactNode;
|
|
50
|
+
/** The tool rail, left of the body; not drawn in a read-only document or in Focus. */
|
|
51
|
+
rail?: ReactNode;
|
|
52
|
+
/** A panel left of the body (slide thumbnails); not drawn in Focus. */
|
|
53
|
+
sidebar?: ReactNode;
|
|
54
|
+
/** Panels right of the body; not drawn in Focus. */
|
|
55
|
+
panels?: ReactNode;
|
|
56
|
+
/** The tool the Focus bar names; the engine's active tool when unset. */
|
|
57
|
+
focusTool?: FocusTool | null;
|
|
58
|
+
children: ReactNode;
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Which tabs a bar `width` wide shows whole: the selected one always, then the others in order
|
|
62
|
+
* while they fit, leaving room for the More tabs button when any is left out. `widths` are the
|
|
63
|
+
* tabs' own; `null` when every tab fits.
|
|
64
|
+
*/
|
|
65
|
+
export declare function fitTabs(ids: readonly string[], widths: ReadonlyMap<string, number>, width: number, active: string | null): Set<string> | null;
|
|
66
|
+
/**
|
|
67
|
+
* How a Classic ribbon gives way at step `level` (0 draws it whole), group by group from the end
|
|
68
|
+
* as Office's does, over `groups` (their keys in ribbon order): 1 draws large buttons small; the
|
|
69
|
+
* next steps draw one more group's buttons as icons alone each, from the last group; then each
|
|
70
|
+
* step collapses one more group, from the last, to one button. `ribbonFitSteps` is the last step.
|
|
71
|
+
*/
|
|
72
|
+
export declare function ribbonFitAt(level: number, groups: readonly string[]): RibbonFit;
|
|
73
|
+
export declare function ribbonFitSteps(groups: number): number;
|
|
74
|
+
export declare function EditorFrame({ tabs, tab, onTab, defaultTab, title, actions, options, rail, sidebar, panels, focusTool, statusBar, children, ...shell }: EditorFrameProps): import("react").JSX.Element;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { type IconComponent } from '@kition/tessera-icons/react';
|
|
2
|
+
/** The tool the Focus bar names (a kit's own rail passes it; the engine's active tool otherwise). */
|
|
3
|
+
export type FocusTool = {
|
|
4
|
+
label: string;
|
|
5
|
+
icon: IconComponent;
|
|
6
|
+
};
|
|
7
|
+
export declare function FocusBar({ tool, onExit }: {
|
|
8
|
+
tool?: FocusTool | null;
|
|
9
|
+
onExit: () => void;
|
|
10
|
+
}): import("react").JSX.Element;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { type CatalogNode } from '../catalogMenus.js';
|
|
2
|
+
import type { FrameTab, MenuTree } from './menus.js';
|
|
3
|
+
export declare function Nodes({ nodes, checked, onKitCommand, onCommand }: {
|
|
4
|
+
nodes: readonly CatalogNode[];
|
|
5
|
+
checked?: MenuTree['checked'];
|
|
6
|
+
onKitCommand?: (command: string) => void;
|
|
7
|
+
onCommand?: (command: string) => void;
|
|
8
|
+
}): import("react").JSX.Element;
|
|
9
|
+
/** A menu tab's drop-down: the kit's `before` actions, then its rows. */
|
|
10
|
+
export declare function MenuNodes({ tree, nodes }: {
|
|
11
|
+
tree: MenuTree;
|
|
12
|
+
nodes: readonly CatalogNode[];
|
|
13
|
+
}): import("react").JSX.Element;
|
|
14
|
+
/**
|
|
15
|
+
* Each menu tab's rows that are drawn: not hidden by the kit (`hidden`), the host, the person
|
|
16
|
+
* (under the catalog's menus or the engine's own), or the session (a commenter's edits). A submenu
|
|
17
|
+
* left empty stays when the host has buttons for it. A menu is built again only when its rows,
|
|
18
|
+
* `hidden`, the configuration, or the commands change.
|
|
19
|
+
*/
|
|
20
|
+
export declare function useVisibleMenus(tabs: readonly FrameTab[]): ReadonlyMap<string, CatalogNode[]>;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { CatalogNode } from '../catalogMenus.js';
|
|
2
|
+
import type { FrameTab } from './menus.js';
|
|
3
|
+
/** How many of its first rows a menu tab shows in Single line's row when its kit names none (`MenuTree.primary`), so the row is never one button. */
|
|
4
|
+
export declare const FALLBACK_PRIMARY = 5;
|
|
5
|
+
export declare function MenuRibbon({ tab, nodes }: {
|
|
6
|
+
tab: FrameTab;
|
|
7
|
+
nodes: readonly CatalogNode[];
|
|
8
|
+
}): import("react").JSX.Element | null;
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { DisplayMode } from './modes.js';
|
|
2
|
+
import type { DisplayModeState } from './useFrameLayout.js';
|
|
3
|
+
export declare function ModeButton({ display, shown, areas }: {
|
|
4
|
+
display: DisplayModeState;
|
|
5
|
+
shown: DisplayMode;
|
|
6
|
+
areas?: boolean;
|
|
7
|
+
}): import("react").JSX.Element | null;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The editor frame's tabs: a kit's command areas, each with a ribbon (its groups, as kits lay them
|
|
3
|
+
* out), a menu (rows of a menu bar's menu), or both; and the builders that turn a menu catalog or
|
|
4
|
+
* the engine's command paths into menu tabs. The frame filters a menu's rows where it draws them
|
|
5
|
+
* (the UI configuration lives inside the editor provider; kits build tabs outside it).
|
|
6
|
+
*/
|
|
7
|
+
import type { ReactNode } from 'react';
|
|
8
|
+
import { type IconComponent } from '@kition/tessera-icons/react';
|
|
9
|
+
import type { KitCommand } from '../engine/kitModule.js';
|
|
10
|
+
import type { MenuRow } from '../uiCatalog.js';
|
|
11
|
+
/** A row a kit adds at the top of a menu tab (Layout's Templates…): a menu item, and a button in the tab's generated ribbon; `primary` shows that button in Single line's row. */
|
|
12
|
+
export type MenuAction = {
|
|
13
|
+
label: string;
|
|
14
|
+
icon?: IconComponent;
|
|
15
|
+
onSelect: () => void;
|
|
16
|
+
testId?: string;
|
|
17
|
+
primary?: boolean;
|
|
18
|
+
};
|
|
19
|
+
/** A menu tab's content: its catalog rows (every path starts with the tab's menu) and how they run. */
|
|
20
|
+
export type MenuTree = {
|
|
21
|
+
rows: readonly MenuRow[];
|
|
22
|
+
/** Rows the kit never shows (commands a browser cannot run); the same function across renders, or the menu is rebuilt. */
|
|
23
|
+
hidden?: (row: MenuRow) => boolean;
|
|
24
|
+
/** Runs a `kit:` row. */
|
|
25
|
+
onKitCommand?: (command: string) => void;
|
|
26
|
+
/** Runs an engine row through the kit's own entry point instead of the editor's `run`. */
|
|
27
|
+
onCommand?: (command: string) => void;
|
|
28
|
+
/** Check marks for rows that toggle. */
|
|
29
|
+
checked?: (command: string) => boolean | undefined;
|
|
30
|
+
before?: readonly MenuAction[];
|
|
31
|
+
/** The row commands (engine ids, and `kit:` rows with their prefix) the generated ribbon shows in Single line's row. */
|
|
32
|
+
primary?: readonly string[];
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* A command area. `ribbon` draws in Single line and Classic (and in Menus as a drop-down panel);
|
|
36
|
+
* `menu` draws in Menus as a drop-down menu, and becomes the ribbon (a command grid) when there is
|
|
37
|
+
* no `ribbon`. `view` keeps the tab in a read-only document.
|
|
38
|
+
*/
|
|
39
|
+
export type FrameTab = {
|
|
40
|
+
id: string;
|
|
41
|
+
label: string;
|
|
42
|
+
view?: boolean;
|
|
43
|
+
ribbon?: ReactNode;
|
|
44
|
+
menu?: MenuTree;
|
|
45
|
+
};
|
|
46
|
+
/** The Kit UI id a tab answers to: a menu tab its menu's (`menu:File`), a ribbon tab `tab:<id>`. */
|
|
47
|
+
export declare function tabUiId(tab: Pick<FrameTab, 'id' | 'menu'>): string;
|
|
48
|
+
export type MenuTabOptions = Pick<MenuTree, 'hidden' | 'onKitCommand' | 'onCommand' | 'checked'> & {
|
|
49
|
+
/** Translates the menus' names (the editor's `phrase`). */
|
|
50
|
+
phrase?: (english: string) => string;
|
|
51
|
+
/** Menus kept in a read-only document (View, Window, Help). */
|
|
52
|
+
view?: readonly string[];
|
|
53
|
+
/** Actions at the top of a menu, by menu name. */
|
|
54
|
+
before?: Readonly<Record<string, readonly MenuAction[]>>;
|
|
55
|
+
/** The row commands Single line's row shows, by menu name (see `MenuTree.primary`). */
|
|
56
|
+
primary?: Readonly<Record<string, readonly string[]>>;
|
|
57
|
+
};
|
|
58
|
+
/** A menu catalog's top-level menus as tabs (a ported app's menu bar). */
|
|
59
|
+
export declare function catalogTabs(catalog: readonly MenuRow[], { phrase, view, before, primary, ...run }?: MenuTabOptions): FrameTab[];
|
|
60
|
+
/** The engine's commands as menu tabs, menus in `order` (others after): a menu's own commands, a separator, then its submenus. */
|
|
61
|
+
export declare function commandMenuTabs(commands: readonly KitCommand[], { order, exclude, ...options }: MenuTabOptions & {
|
|
62
|
+
order: readonly string[];
|
|
63
|
+
exclude?: readonly string[];
|
|
64
|
+
}): FrameTab[];
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The editor's display modes (Kit UI protocol section 9, display modes): the four modes, what the
|
|
3
|
+
* host allows and presets (`ui.modes`), the person's stored choice, and which mode fits the
|
|
4
|
+
* editor's width. Pure functions over plain values; no React.
|
|
5
|
+
*/
|
|
6
|
+
import type { KitDisplayMode } from '@kition/kit-ui-protocol';
|
|
7
|
+
export type DisplayMode = KitDisplayMode;
|
|
8
|
+
/** A mode a kit may default to (`kit.json` `ui.display`) and the person's stored choice: Focus is entered, never kept. */
|
|
9
|
+
export type KitDisplay = Exclude<DisplayMode, 'focus'>;
|
|
10
|
+
export declare const DISPLAY_MODES: readonly DisplayMode[];
|
|
11
|
+
/** The narrowest editor that still shows the single line of commands; narrower, it steps down to Menus. */
|
|
12
|
+
export declare const LINE_MIN_WIDTH = 720;
|
|
13
|
+
export declare function isDisplayMode(value: unknown): value is DisplayMode;
|
|
14
|
+
/** A `kit.json` `ui.display` (JSON, so checked at runtime); null when absent or not a kit default. */
|
|
15
|
+
export declare function validDisplay(value: unknown): KitDisplay | null;
|
|
16
|
+
export declare function modeStorageKey(kit: string): string;
|
|
17
|
+
/** The person's stored mode for `kit`; null when none, unreadable, or no storage (a sandboxed frame). */
|
|
18
|
+
export declare function readStoredMode(kit: string): KitDisplay | null;
|
|
19
|
+
/** Keeps the person's mode for `kit`; without storage the choice lasts for this page only. */
|
|
20
|
+
export declare function writeStoredMode(kit: string, mode: KitDisplay): void;
|
|
21
|
+
/** The host's `ui.modes`, parsed: null `allowed` allows every mode, null `default` presets none. */
|
|
22
|
+
export type ModeRules = {
|
|
23
|
+
allowed: readonly DisplayMode[] | null;
|
|
24
|
+
default: DisplayMode | null;
|
|
25
|
+
};
|
|
26
|
+
export declare const NO_MODE_RULES: ModeRules;
|
|
27
|
+
/** The modes the person may choose, in `DISPLAY_MODES` order: every mode unless the host lists some. */
|
|
28
|
+
export declare function allowedModes(rules: ModeRules): readonly DisplayMode[];
|
|
29
|
+
/**
|
|
30
|
+
* The mode the editor shows before fitting (UI-C7): the person's stored choice, else the host's
|
|
31
|
+
* preset, else Menus for a read-only document, else the kit's default, else Single line, each
|
|
32
|
+
* only when the host allows it; failing all, the first allowed mode that is not Focus, else Menus.
|
|
33
|
+
*/
|
|
34
|
+
export declare function chosenMode({ stored, rules, kit, readOnly }: {
|
|
35
|
+
stored: KitDisplay | null;
|
|
36
|
+
rules: ModeRules;
|
|
37
|
+
kit: KitDisplay | null;
|
|
38
|
+
readOnly: boolean;
|
|
39
|
+
}): KitDisplay;
|
|
40
|
+
/** The editor width each mode's commands needed when last shown, for the selected tab. */
|
|
41
|
+
export type ModeNeeds = {
|
|
42
|
+
classic?: number;
|
|
43
|
+
line?: number;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* The mode that fits `width` (UI-C8): `chosen`, stepped down Classic, Single line, Menus while it
|
|
47
|
+
* does not fit. Single line needs at least `LINE_MIN_WIDTH`, and each needs what its commands
|
|
48
|
+
* last measured; Menus always fits. A step skips modes the host does not allow; when none fits,
|
|
49
|
+
* the lowest allowed one shows (and scrolls).
|
|
50
|
+
*/
|
|
51
|
+
export declare function stepDown(chosen: KitDisplay, width: number, needs: ModeNeeds, allowed: readonly DisplayMode[]): KitDisplay;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The frame's layout state: the person's display mode (stored per kit, within what the host
|
|
3
|
+
* allows), the mode that fits the frame's width (step-down), and touch sizing.
|
|
4
|
+
*/
|
|
5
|
+
import { type RefObject } from 'react';
|
|
6
|
+
import type { HostConnection } from '../host.js';
|
|
7
|
+
import { type DisplayMode, type KitDisplay } from './modes.js';
|
|
8
|
+
export type DisplayModeState = {
|
|
9
|
+
/** The mode the person chose (or the default), before fitting. */
|
|
10
|
+
chosen: KitDisplay;
|
|
11
|
+
focus: boolean;
|
|
12
|
+
allowed: readonly DisplayMode[];
|
|
13
|
+
/** Chooses a mode: Menus, Single line, or Classic is kept for the kit; Focus lasts until left. */
|
|
14
|
+
choose: (mode: DisplayMode) => void;
|
|
15
|
+
toggleFocus: () => void;
|
|
16
|
+
exitFocus: () => void;
|
|
17
|
+
};
|
|
18
|
+
/**
|
|
19
|
+
* The person's display mode. `areas` is false for a frame without tabs, where Menus, Single line,
|
|
20
|
+
* and Classic draw the same: it then shows Menus, and allows only Menus and Focus.
|
|
21
|
+
*/
|
|
22
|
+
export declare function useDisplayMode(host: HostConnection, areas?: boolean): DisplayModeState;
|
|
23
|
+
/**
|
|
24
|
+
* The mode that fits: the frame's width (a `ResizeObserver` on its root; unbounded without one),
|
|
25
|
+
* and per mode and tab the width its commands needed when they last overflowed. `measure` reads a
|
|
26
|
+
* shown command row: one that overflows needs the frame's width plus what did not fit; one that
|
|
27
|
+
* fits needs no more than the frame's width, and records nothing more.
|
|
28
|
+
*/
|
|
29
|
+
export declare function useStepDown(root: RefObject<HTMLElement | null>, chosen: KitDisplay, tab: string, allowed: readonly DisplayMode[]): {
|
|
30
|
+
effective: KitDisplay;
|
|
31
|
+
measure: (mode: "classic" | "line", panel: HTMLElement | null) => void;
|
|
32
|
+
};
|
|
33
|
+
/** Whether the main pointer is coarse (a finger): the frame then sizes for touch. */
|
|
34
|
+
export declare function useTouchDensity(): boolean;
|