@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.
Files changed (67) hide show
  1. package/README.md +103 -2
  2. package/dist/LICENSE +177 -0
  3. package/dist/THIRD_PARTY_NOTICES +28 -0
  4. package/dist/assets/kitEngine.worker-Bb4qhbsX.js +13038 -0
  5. package/dist/chunks/workspaceTree-CpJ2i9hy.js +23 -0
  6. package/dist/index.js +6434 -0
  7. package/dist/styles.css +807 -0
  8. package/dist/types/src/CommandDialog.d.ts +22 -0
  9. package/dist/types/src/CommentsPanel.d.ts +45 -0
  10. package/dist/types/src/CustomizeDialog.d.ts +32 -0
  11. package/dist/types/src/HostButtons.d.ts +11 -0
  12. package/dist/types/src/RenderFailure.d.ts +7 -0
  13. package/dist/types/src/TextSink.d.ts +6 -0
  14. package/dist/types/src/brand.d.ts +2 -0
  15. package/dist/types/src/catalogMenus.d.ts +27 -0
  16. package/dist/types/src/chart.d.ts +138 -0
  17. package/dist/types/src/conflicts.d.ts +12 -0
  18. package/dist/types/src/drawing.d.ts +83 -0
  19. package/dist/types/src/editor.d.ts +544 -0
  20. package/dist/types/src/engine/KitCanvas.d.ts +70 -0
  21. package/dist/types/src/engine/createKitFile.d.ts +12 -0
  22. package/dist/types/src/engine/decorations.d.ts +14 -0
  23. package/dist/types/src/engine/engineOverlays.d.ts +197 -0
  24. package/dist/types/src/engine/engineTools.d.ts +116 -0
  25. package/dist/types/src/engine/kitDraft.d.ts +70 -0
  26. package/dist/types/src/engine/kitEngine.d.ts +370 -0
  27. package/dist/types/src/engine/kitEngine.worker.d.ts +30 -0
  28. package/dist/types/src/engine/kitHost.d.ts +41 -0
  29. package/dist/types/src/engine/kitModel.d.ts +32 -0
  30. package/dist/types/src/engine/kitModelRunner.d.ts +99 -0
  31. package/dist/types/src/engine/kitModule.d.ts +173 -0
  32. package/dist/types/src/engine/kitShortcuts.d.ts +32 -0
  33. package/dist/types/src/engine/kitTools.d.ts +79 -0
  34. package/dist/types/src/engine/lentFiles.d.ts +29 -0
  35. package/dist/types/src/engine/rasterViewport.d.ts +178 -0
  36. package/dist/types/src/engine/readOnly.d.ts +78 -0
  37. package/dist/types/src/engine/refusal.d.ts +39 -0
  38. package/dist/types/src/engine/replica.d.ts +23 -0
  39. package/dist/types/src/engine/useKitDocument.d.ts +154 -0
  40. package/dist/types/src/engine/workerRelay.d.ts +62 -0
  41. package/dist/types/src/files.d.ts +74 -0
  42. package/dist/types/src/frame/EditorFrame.d.ts +74 -0
  43. package/dist/types/src/frame/FocusBar.d.ts +10 -0
  44. package/dist/types/src/frame/MenuNodes.d.ts +20 -0
  45. package/dist/types/src/frame/MenuRibbon.d.ts +8 -0
  46. package/dist/types/src/frame/ModeButton.d.ts +7 -0
  47. package/dist/types/src/frame/menus.d.ts +64 -0
  48. package/dist/types/src/frame/modes.d.ts +51 -0
  49. package/dist/types/src/frame/useFrameLayout.d.ts +34 -0
  50. package/dist/types/src/host.d.ts +127 -0
  51. package/dist/types/src/index.d.ts +84 -0
  52. package/dist/types/src/ink.d.ts +26 -0
  53. package/dist/types/src/lease.d.ts +53 -0
  54. package/dist/types/src/oneInFlight.d.ts +7 -0
  55. package/dist/types/src/phrases.d.ts +25 -0
  56. package/dist/types/src/presence.d.ts +79 -0
  57. package/dist/types/src/strings.d.ts +6 -0
  58. package/dist/types/src/toolIcons.d.ts +32 -0
  59. package/dist/types/src/uiCatalog.d.ts +59 -0
  60. package/dist/types/src/uiConfig.d.ts +53 -0
  61. package/dist/types/src/uiContext.d.ts +65 -0
  62. package/dist/types/src/uiStore.d.ts +20 -0
  63. package/dist/types/src/useCommentAnchors.d.ts +29 -0
  64. package/dist/types/src/useKitSession.d.ts +115 -0
  65. package/dist/types/src/workspaceTree.d.ts +5 -0
  66. package/dist/workspaceTree.js +1 -0
  67. package/package.json +43 -3
@@ -0,0 +1,127 @@
1
+ /**
2
+ * The kit's side of the Kit UI protocol (Kition platform docs/platform/reference/ui-protocol.md): wait for the host's port, take
3
+ * `ui/initialize`, and offer the host's file calls as a `KitHost` the engine hooks use.
4
+ */
5
+ import { type InitializeParams, type KitCommentAnchor, type KitDocumentPermissions, type KitHostService, type KitHostServices, type KitShownThread, type KitLinksPickParams, type KitNotifications, type KitPickedLink, type KitSidePeer, type KitTheme, type KitView, type KitWatermark } from '@kition/kit-ui-protocol';
6
+ import { type KitBrand } from './brand.js';
7
+ import { type KitDisplay } from './frame/modes.js';
8
+ import type { KitHost } from './engine/kitHost.js';
9
+ import { type KitFilesClient } from './files.js';
10
+ import { type UiStore } from './uiStore.js';
11
+ import type { KitUiDeclaration } from './uiCatalog.js';
12
+ export type { InitializeParams, KitTheme };
13
+ /** The kit's connection to its host. */
14
+ export type HostConnection = {
15
+ peer: KitSidePeer;
16
+ init: InitializeParams;
17
+ /** The document's file, through the host; with its stored replica when `replica`. */
18
+ files: KitHost;
19
+ /**
20
+ * Files beyond the document, through handles the host grants (KitFiles 1.0, protocol section
21
+ * 7g): pick, create, read, write in chunks, list, print, and an engine's outputs (E16).
22
+ */
23
+ kitFiles: KitFilesClient;
24
+ /** The host keeps replicas and the kit declared `replica`: it serves `replica/*` too. */
25
+ replica: boolean;
26
+ /**
27
+ * The document is read-only for this session (`document.readOnly`): the kit refuses edits
28
+ * with the reason `read-only`. It never changes; a host reopens the kit to change it. Absent: false.
29
+ */
30
+ readOnly?: boolean;
31
+ /**
32
+ * Where in the document to show first (`document.view`, protocol section 2, minor version 2.1),
33
+ * checked; null when the host named none. The kit shows it once its document is open, or ignores it.
34
+ */
35
+ view: KitView | null;
36
+ /**
37
+ * What the person may take out of the document (`document.permissions`, protocol 2.6): the kit
38
+ * hides Download, Export and Print, and Share controls whose flag is false. All true when the
39
+ * host sent none.
40
+ */
41
+ permissions: KitDocumentPermissions;
42
+ /** The text to draw over the canvas (`document.watermark`, protocol 2.6), checked; null for none. */
43
+ watermark: KitWatermark | null;
44
+ /**
45
+ * Hears the host's `document/reveal` (section 7i, OP3): show `view` in the open document. The
46
+ * view is checked; malformed ones are dropped. Answers an unsubscribe.
47
+ */
48
+ onReveal: (listener: (view: KitView) => void) => () => void;
49
+ /** The UI configuration (protocol section 9). */
50
+ ui: UiStore;
51
+ /** The kit's brand color, from its kit.json (standard U5b). */
52
+ brand: KitBrand | null;
53
+ /** The kit, as it named itself to `connectHost`: its id keys the person's display mode. */
54
+ kit: {
55
+ id: string;
56
+ version: string;
57
+ };
58
+ /** The kit's default display mode, from its kit.json `ui.display` (platform U5c); null when it names none. */
59
+ display: KitDisplay | null;
60
+ /** The kit's declared elements; null when it does not honor UI configuration. */
61
+ declaration: KitUiDeclaration | null;
62
+ /**
63
+ * Tells the host the kit opened the document; answers `ui/initialize`. `extra` are capabilities
64
+ * known only once the document's engine runs (`model`).
65
+ */
66
+ opened: (extra?: string[]) => void;
67
+ /** Tells the host the document could not be opened. */
68
+ failed: (error: unknown) => void;
69
+ changed: (state: KitNotifications['document/changed']) => void;
70
+ notify: (notice: KitNotifications['host/notify']) => void;
71
+ openAgent: (prompt?: string) => Promise<void>;
72
+ pick: (purpose: string, accept: string[]) => Promise<string | null>;
73
+ /**
74
+ * Asks the person for existing workspace files to link (`links/pick`, capability `links-pick`,
75
+ * section 7i; UI-N2): the host copies nothing and answers each by its path relative to the
76
+ * document's folder, which the kit then reads with `files.read` and `files.stamp` (UI-N3).
77
+ * Send it only from a person's gesture; none when the person cancels.
78
+ */
79
+ pickLinks: (params: KitLinksPickParams) => Promise<KitPickedLink[]>;
80
+ /**
81
+ * Writes a new file next to the document (an export, a rendered movie): the host keeps
82
+ * existing files and may change the name to an unused one; answers the path it wrote.
83
+ */
84
+ exportFile: (path: string, bytes: Uint8Array) => Promise<string>;
85
+ /** Whether the host serves `service` (capability `service:<id>`, protocol 2.6 section 7k). */
86
+ hasService: (service: KitHostService) => boolean;
87
+ /**
88
+ * Asks the host for one of its services (`host/service`, section 7k; managed co-editing D4):
89
+ * only from a person's gesture (UI-V1), and only for a service it serves; one it does not is
90
+ * refused here (`-32000`, reason `not-allowed`) without asking. A kit with a host service shows
91
+ * no version of its own (UI-V2).
92
+ */
93
+ service: <S extends KitHostService>(service: S, params: KitHostServices[S][0]) => Promise<KitHostServices[S][1]>;
94
+ /** The host keeps comment threads itself and marks them through the kit (capability `comment-anchors`). */
95
+ commentAnchors: boolean;
96
+ /** Hears the host's threads to mark (`comments/show`), checked: the whole list each time. Answers an unsubscribe. */
97
+ onComments: (listener: (threads: KitShownThread[]) => void) => () => void;
98
+ /** Tells the host the person clicked a thread's marker (`comments/activated`). */
99
+ activateComment: (id: string) => void;
100
+ /** Answers the host's `comments/locate` with `locate`: whether each anchor is found in the document now. */
101
+ locateComments: (locate: (anchors: KitCommentAnchor[]) => boolean[] | Promise<boolean[]>) => void;
102
+ /** Removes the window listeners. */
103
+ close: () => void;
104
+ };
105
+ /**
106
+ * Applies the host's theme tokens to the document root (protocol section 4), then the kit's
107
+ * brand over the primary tokens unless the host keeps its own (`theme.brand: "host"`, section 9).
108
+ * Clears a previous brand's tokens first, so a later `theme.brand: "host"` does not leave them
109
+ * stale under the host's own primary tokens.
110
+ */
111
+ export declare function applyTheme(theme: KitTheme, brand?: KitBrand | null, root?: HTMLElement): void;
112
+ export declare const isMac: () => boolean;
113
+ /**
114
+ * Waits for the host's handshake and its `ui/initialize`. The kit then opens the document and
115
+ * calls `opened()` (or `failed()`), which answers the host. Options name the kit; `brand` is its
116
+ * kit.json `ui.brand`, `display` its `ui.display`, and `ui` its declared elements (with it, the kit
117
+ * honors UI configuration).
118
+ * Passing `ui` requires the editor to mount `KitEditorProvider`, which answers `ui/elements`.
119
+ */
120
+ export declare function connectHost(kit: {
121
+ id: string;
122
+ version: string;
123
+ capabilities?: string[];
124
+ brand?: KitBrand;
125
+ ui?: KitUiDeclaration;
126
+ display?: string;
127
+ }): Promise<HostConnection>;
@@ -0,0 +1,84 @@
1
+ /**
2
+ * @kition/kit-editor: build a kit's embedded editor (the Kition kit platform's kit editors, docs/platform/kits/ui.md). The host connection
3
+ * (`connectHost`) and document session (`useKitSession`), the engine client, canvas, and engine
4
+ * tools, and shared components styled with the host's theme. Import `@kition/kit-editor/styles.css`
5
+ * once. The shared components come from Kition Tessera (`@kition/tessera-ui`) and are re-exported
6
+ * here under the same names.
7
+ */
8
+ export { connectHost, applyTheme, isMac, type HostConnection, type InitializeParams, type KitTheme } from './host.js';
9
+ export { createFilesClient, FILE_CHUNK_BYTES, type KitEngineOutput, type KitFilesClient } from './files.js';
10
+ export { fileErrorReason, type KitFileErrorReason, type KitFileStat, type KitFilesPickParams } from '@kition/kit-ui-protocol';
11
+ export { useKitSession, type KitSessionOptions } from './useKitSession.js';
12
+ export { createStrings, type Catalog } from './strings.js';
13
+ export { TextSink } from './TextSink.js';
14
+ export { CommandDialog, needsParams } from './CommandDialog.js';
15
+ export { PreviewDialog, type PreviewDialogPreview, type PreviewDialogProps, type PreviewStatus } from '@kition/tessera-ui';
16
+ export { Button, ColorGrid, ContextMenu, Dialog, ICON_STROKE, IconButton, LineMoreLabelContext, MenuButton, MenuItem, MenuSeparator, OverflowStrip, PALETTE_COLORS, Panel, RibbonButton, RibbonGroup, RibbonItem, RibbonPresentationContext, RibbonRow, RibbonStack, STANDARD_COLORS, StatusBar, StatusSpacer, TableSizePicker, Toaster, ZoomControl, lineSize, menuKeyDown, overflowOf, toast, type ContextMenuPoint, type RibbonButtonProps, type RibbonPresentation, } from '@kition/tessera-ui';
17
+ export { DRAWING_SHAPES, DRAWING_WARPS, DRAWING_WEIGHTS, DrawingFormatGroup, DrawingInsertGroup, DrawingWarpMenu } from './drawing.js';
18
+ export { INK_TOOLS, INK_WEIGHTS, InkGroup, type DrawState } from './ink.js';
19
+ export { CHART_FORMATS, CHART_KINDS, CHART_MARKERS, ChartAxisDialog, ChartDataDialog, ChartDesignGroups, ChartInsertMenu, ChartSeriesDialog, labelPositions, linesOf, useChartSpec, type ChartAxis, type ChartFormat, type ChartSpec } from './chart.js';
20
+ export { NumberField, type NumberFieldProps } from '@kition/tessera-ui';
21
+ export { BarChart, LineChart, PieChart, useAutoSize, type AutoSize, type BarChartProps, type ChartHeight, type LineChartProps, type PieChartProps, type ToastId, type ToastLevel, type ToastOptions } from '@kition/tessera-ui';
22
+ export { Badge, Card, CardContent, CardHeader, Command, CommandEmpty, CommandGroup, CommandInput, CommandItem as CommandListItem, CommandList, CommandSeparator, CommandShortcut, ConfirmProvider, Disclosure, Field, Modal, ModalBody, ModalClose, ModalCloseButton, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalTitle, ModalTrigger, PasswordInput, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Select, Sheet, Spinner, Switch, TextInput, Textarea, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, useConfirm, useDialogFocus, useDismissableLayer, useMediaQuery, type ButtonVariant, type ConfirmFn, type ConfirmOptions, type ControlSize, type ModalContentProps, type SheetProps, type TesseraButtonProps, } from '@kition/tessera-ui';
23
+ export { BarSeparator, Checkbox, Choice, Hint, Segmented, type CheckboxProps, type ChoiceProps, type Segment, type SegmentedProps } from '@kition/tessera-ui';
24
+ /** The workspace frame tree's functions (`workspaceTree.closePanel`, `workspaceTree.validateTree`, …). */
25
+ export * as workspaceTree from './workspaceTree.js';
26
+ export type { WorkspaceNode, WorkspaceSize, WorkspaceSplit, WorkspaceTabs } from './workspaceTree.js';
27
+ export { WorkspaceLayout, type WorkspaceLayoutProps, type WorkspacePanel } from '@kition/tessera-ui';
28
+ export { DockArea, dockHeights, type DockAreaHandle, type DockAreaProps, type DockGroup, type DockSizing, type DockTab } from '@kition/tessera-ui';
29
+ export { FloatingPanels, automaticFloatingPosition, clampFloatingRect, resizeFloatingRect, type FloatingEdge, type FloatingPanel, type FloatingPanelsProps, type FloatingRect, type FloatingSize } from '@kition/tessera-ui';
30
+ export { EyeButton, PanelFooter, RenameField, Thumbnail, deviceScale, type EyeSweep, type ThumbnailImage } from '@kition/tessera-ui';
31
+ export { useWorkspaces, workspaceSlug, WORKSPACE_ACTIONS, type SavedWorkspace, type WorkspacePrefs, type Workspaces, type WorkspacesOptions } from '@kition/tessera-ui';
32
+ export { kitStoreKey, readKitStore, removeKitStore, storedBytes, useKitStore, writeKitStore, type KitStoreOptions, type KitStoreWrite } from '@kition/tessera-ui';
33
+ export { Histogram, rankScale, smoothHistogram, type HistogramProps } from '@kition/tessera-ui';
34
+ export { TimecodeField, formatTimecode, parseTimecode, type TimecodeFieldProps } from '@kition/tessera-ui';
35
+ export { TransportBar, type TransportButton } from '@kition/tessera-ui';
36
+ export { LevelMeter, meterFraction, meterLayout, type LevelMeterHandle, type LevelMeterProps, type MeterBox, type MeterLayout } from '@kition/tessera-ui';
37
+ export { KeyframeLane, type Keyframe, type KeyframeLaneProps } from '@kition/tessera-ui';
38
+ export { ColorPicker, parseHex, rgbToHex, type ColorPickerProps, type RGB } from '@kition/tessera-ui';
39
+ export { CurveEditor, RGB_IDENTITY, addCurvePoint, hitCurvePoint, moveCurvePoint, removeCurvePoint, sampleCurve, sortCurve, type CurveEditorProps, type CurveKind, type CurvePoint } from '@kition/tessera-ui';
40
+ export { ColorWheel, lightnessAt, wheelRadius, wheelValueAt, type ColorWheelProps } from '@kition/tessera-ui';
41
+ export { GradientSlider, SLIDER_GRADIENTS, sliderFraction, sliderValueAt, type GradientSliderProps } from '@kition/tessera-ui';
42
+ export type { DragPhase } from '@kition/tessera-ui';
43
+ export { EditorFrame, FrameChrome, useFrameDisplay, useFrameMode, type EditorFrameProps } from './frame/EditorFrame.js';
44
+ export type { DisplayModeState } from './frame/useFrameLayout.js';
45
+ export { catalogTabs, commandMenuTabs, tabUiId, type FrameTab, type MenuAction, type MenuTabOptions, type MenuTree } from './frame/menus.js';
46
+ export { DISPLAY_MODES, LINE_MIN_WIDTH, modeStorageKey, type DisplayMode, type KitDisplay } from './frame/modes.js';
47
+ export type { FocusTool } from './frame/FocusBar.js';
48
+ export { catalogMenuTree, type CatalogMenu, type CatalogNode } from './catalogMenus.js';
49
+ export type { MenuRow } from './uiCatalog.js';
50
+ export { KitCanvas, type KitCanvasHandle, type KitCanvasView } from './engine/KitCanvas.js';
51
+ export { KitEngine, type KitEngineInfo, type KitEngineSchema } from './engine/kitEngine.js';
52
+ export { WorkerRelay, type EngineReplica, type WorkerRelayOptions, type WorkerRelayPage } from './engine/workerRelay.js';
53
+ export { useEngineTools, type EngineToolInfo } from './engine/engineTools.js';
54
+ export { DEFAULT_OVERLAY_STYLE, drawEngineOverlays, drawOverlayInStyle, overlayCss, overlayStyle, type EngineOverlay, type OverlayDrawContext, type OverlayDrawer, type OverlayRgba, type OverlayStyle, type OverlayStylePatch, } from './engine/engineOverlays.js';
55
+ export { HAND_TOOL, ZOOM_TOOL, dragRect, type KitPointer, type KitTool } from './engine/kitTools.js';
56
+ export type { KitCommand, KitModuleManifest, KitModuleRuntime } from './engine/kitModule.js';
57
+ export type { RasterDecoration, RasterPane, RasterPins, RasterRect, RasterView, RasterViewportStats } from './engine/rasterViewport.js';
58
+ export { viewPanes } from './engine/rasterViewport.js';
59
+ export { stackDecorations } from './engine/decorations.js';
60
+ export { FileChangedError, isFileChangedError } from './engine/useKitDocument.js';
61
+ export type { KitChange, KitDocumentOptions, KitRefresh, KitRepaint, KitRepaints, KitRunOptions } from './engine/useKitDocument.js';
62
+ export { RESERVED_SHORTCUTS, bindableShortcut, commandForShortcut, shortcutMatches } from './engine/kitShortcuts.js';
63
+ export { oneInFlight } from './oneInFlight.js';
64
+ export { kitLeases, leaseHeldByOther, scopesCollide, useLease, useLeases, type KitLease, type KitLeases, type LeaseOutcome } from './lease.js';
65
+ export { parseConflicts, reportConflicts, useConflictReport, type KitConflict } from './conflicts.js';
66
+ export { drawPresence, kitPresence, peerColor, remoteCarets, remoteSelections, usePresence, useRemoteCarets, useRemoteSelections, PRESENCE_INTERVAL_MS, type KitPeerPresence, type KitPresence, type KitPresenceCaret, type KitPresenceStore, type PresenceRect, type RemoteCaret, type RemoteSelection } from './presence.js';
67
+ export { CommentsPanel, COMMENTS_PANEL_LABELS, type CommentsPanelLabels, type CommentsPanelProps } from './CommentsPanel.js';
68
+ export { commentMarkers, useCommentAnchors, type CommentAnchorsOptions, type CommentMarker, type CommentMarkerRect } from './useCommentAnchors.js';
69
+ export { READ_ONLY_REASON, READ_ONLY_RULES, ReadOnlyError, editsDocument, isReadOnlyError } from './engine/readOnly.js';
70
+ export { KIT_UI_CATALOGS, createKitStrings, useKitEditorState, KitEditorProvider, useKitEditor, useKitTools, useReadOnly, CommandButton, ToolButton, RibbonMenu, CommandItem, CommandTab, commandGroups, commandsOfGroup, CommandGroupButtons, commandMenus, KitDocumentCanvas, SubMenu, ToolRail, EngineToolRail, PanelSection, type RailTool, type KitReport, type KitEditorOptions, type KitHistory, base64, PICTURE_TYPES, useHostPick, useEngineQuery, type KitEditor, type KitSession, type KitTools, type Strings, } from './editor.js';
71
+ export { loadPhrases, parsePhrases, parseRustPhrases, catalogNames, withPhrases, type Phrases } from './phrases.js';
72
+ export { COMMAND_FALLBACK_ICON, commandIcon, registerCommandIcons, toolIcon } from './toolIcons.js';
73
+ /** Tessera Icons, for kits that take everything from kit-editor (`TesseraIcons.StarIcon`); bundlers keep only the icons used. */
74
+ export * as TesseraIcons from '@kition/tessera-icons/react';
75
+ /** The type of an icon prop: Tessera's icons, or another set's with the same props. */
76
+ export type { IconComponent, IconProps } from '@kition/tessera-icons/react';
77
+ export { defineKitUi, type KitUiDeclaration, type KitUiItem } from './uiCatalog.js';
78
+ export { KitElement, useUi } from './uiContext.js';
79
+ export { HostButtons, HOST_ICONS } from './HostButtons.js';
80
+ export { brandTokens, contrast, type KitBrand } from './brand.js';
81
+ export type { UiConfig, UiState } from './uiConfig.js';
82
+ export type { UiStore } from './uiStore.js';
83
+ export type { KitUiElement, KitUiHostButton, KitUiConfig, KitView } from '@kition/kit-ui-protocol';
84
+ export { isOpenableUrl, openErrorReason, type KitLinkRef, type KitOpenErrorReason, type KitOpenParams, type KitOpenResult } from '@kition/kit-ui-protocol';
@@ -0,0 +1,26 @@
1
+ import { type IconComponent } from "@kition/tessera-icons/react";
2
+ /**
3
+ * The Draw tab's pens, shared by every kit that implements `KitDrawing 1.2`'s ink. Each kit has
4
+ * the same commands for them (`draw.select`, `draw.pen`, `draw.pencil`, `draw.highlighter`,
5
+ * `draw.eraser`, each pen taking `{color?, width?}`, and `draw.state` answering `{tool, color,
6
+ * width}`); a kit whose engine has a tool of the same id is switched through its tools, so its
7
+ * tool rail and the ribbon agree. Drawing and erasing are the kit's pointer gestures, which run
8
+ * `drawing.ink` and `drawing.erase`, as an agent does.
9
+ */
10
+ /** What `draw.state` answers. */
11
+ export type DrawState = {
12
+ tool: string;
13
+ color: string;
14
+ width: number;
15
+ };
16
+ /** The pens and tools, by command name. */
17
+ export declare const INK_TOOLS: ReadonlyArray<{
18
+ tool: string;
19
+ icon: IconComponent;
20
+ label: string;
21
+ }>;
22
+ /** Pen thicknesses in points. */
23
+ export declare const INK_WEIGHTS: number[];
24
+ export declare function InkGroup({ testId }: {
25
+ testId?: string;
26
+ }): import("react").JSX.Element;
@@ -0,0 +1,53 @@
1
+ import { type KitLease } from '@kition/kit-ui-protocol';
2
+ import type { HostConnection } from './host.js';
3
+ export type { KitLease };
4
+ /**
5
+ * What `acquire` answers: granted (`lease` null when nobody is there to coordinate with, which
6
+ * includes a host that is offline: edits made then are allowed, and land as conflict objects if
7
+ * someone else held the lease meanwhile), or refused, with who holds it when another session does.
8
+ */
9
+ export type LeaseOutcome = {
10
+ granted: true;
11
+ lease: KitLease | null;
12
+ } | {
13
+ granted: false;
14
+ reason: 'held' | 'read-only';
15
+ holder: KitLease['holder'] | null;
16
+ };
17
+ /** A document's leases, seen from its kit. */
18
+ export type KitLeases = {
19
+ /** The host serves leases (the document may be co-edited). */
20
+ readonly available: boolean;
21
+ /** The document's leases as last heard. */
22
+ list: () => KitLease[];
23
+ subscribe: (listener: () => void) => () => void;
24
+ /** The lease another session holds on a scope colliding with `scope`, if any. */
25
+ heldByOther: (scope: string) => KitLease | null;
26
+ acquire: (scope: string, ttl?: number) => Promise<LeaseOutcome>;
27
+ release: (scope: string) => Promise<void>;
28
+ };
29
+ /** Whether two scopes collide: equal, or either is `*` (the whole document). */
30
+ export declare function scopesCollide(a: string, b: string): boolean;
31
+ /** The lease in `leases` another session holds on a scope colliding with `scope`, if any. */
32
+ export declare function leaseHeldByOther(leases: readonly KitLease[], scope: string): KitLease | null;
33
+ /** The document's leases for the kit connected through `host` (one store per connection). */
34
+ export declare function kitLeases(host: HostConnection): KitLeases;
35
+ /** The document's leases, following changes (inside `KitEditorProvider`). */
36
+ export declare function useLeases(): KitLeases & {
37
+ leases: KitLease[];
38
+ };
39
+ /**
40
+ * One scope's lease (inside `KitEditorProvider`): `heldBy` is who else holds it (or a colliding
41
+ * scope), `mine` whether this session does; `acquire` and `release` act on it. `scope` null
42
+ * (nothing to coordinate) is never held.
43
+ */
44
+ export declare function useLease(scope: string | null): {
45
+ heldBy: {
46
+ principalId: string;
47
+ name: string;
48
+ self: boolean;
49
+ } | null;
50
+ mine: boolean;
51
+ acquire: (ttl?: number) => Promise<LeaseOutcome>;
52
+ release: () => Promise<void>;
53
+ };
@@ -0,0 +1,7 @@
1
+ /**
2
+ * A read that keeps one request in flight: asked while a read runs, it runs once more after that
3
+ * read (however many times it was asked meanwhile), so the last answer always follows the last
4
+ * ask. Every ask answers when the read that covers it has finished. A failed read is reported to
5
+ * `onError` (or ignored) and does not stop the next one.
6
+ */
7
+ export declare function oneInFlight(read: () => Promise<void>, onError?: (error: unknown) => void): () => Promise<void>;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Translations of a kit's English interface text (command titles, menu and group names) from the
3
+ * catalogs its upstream editor already ships, in either form:
4
+ * - `*.tsv`: `context <TAB> English <TAB> translation` lines (`#` starts a comment; `\n`, `\t`,
5
+ * `\\` are escapes);
6
+ * - `*.rs`: a Rust `match` table of `"English" => "translation",` arms.
7
+ * A kit loads them with `import.meta.glob('…/i18n/*.tsv', { query: '?raw', import: 'default' })`.
8
+ */
9
+ export type Phrases = (english: string) => string;
10
+ /** One catalog's English → translation table. */
11
+ export declare function parsePhrases(tsv: string): Map<string, string>;
12
+ /** One Rust `match` table's English → translation arms. */
13
+ export declare function parseRustPhrases(source: string): Map<string, string>;
14
+ /** The catalog names a locale may be in, best first: `zh-CN` → `zh-hans`, `pt-BR` → `pt-br`. */
15
+ export declare function catalogNames(locale: string): string[];
16
+ /**
17
+ * The phrases for `locale` from `loaders` (path → its text, as from `import.meta.glob`); English
18
+ * text passes through unchanged when no catalog matches or a phrase is missing.
19
+ */
20
+ export declare function loadPhrases(loaders: Record<string, () => Promise<unknown>>, locale: string): Promise<Phrases>;
21
+ /**
22
+ * `upstream` with a kit's own translations of English labels checked first (`extra[locale]`,
23
+ * with the same locale fallbacks), for labels the upstream catalog lacks.
24
+ */
25
+ export declare function withPhrases(upstream: Phrases, extra: Record<string, Record<string, string>>, locale: string): Phrases;
@@ -0,0 +1,79 @@
1
+ import { type KitPeerPresence, type KitPresence, type KitPresenceCaret } from '@kition/kit-ui-protocol';
2
+ import type { HostConnection } from './host.js';
3
+ export type { KitPeerPresence, KitPresence, KitPresenceCaret };
4
+ /** How often at most a kit shares its presence while it changes (UI-P1), in milliseconds. */
5
+ export declare const PRESENCE_INTERVAL_MS = 100;
6
+ /** A document's presence, seen from its kit. */
7
+ export type KitPresenceStore = {
8
+ /** The host serves presence (the document may be co-edited). */
9
+ readonly available: boolean;
10
+ /** The other people in the document, as last heard. */
11
+ peers: () => KitPeerPresence[];
12
+ subscribe: (listener: () => void) => () => void;
13
+ /**
14
+ * Shares `presence`: at once, or, while it changes faster than every `PRESENCE_INTERVAL_MS`,
15
+ * the last one when the interval ends. A presence equal to the last one shared is not sent again.
16
+ */
17
+ set: (presence: KitPresence) => void;
18
+ };
19
+ /** The presence of the document the kit connected through `host` (one store per connection). */
20
+ export declare function kitPresence(host: HostConnection): KitPresenceStore;
21
+ /**
22
+ * The other people in the document, following changes, and this session's presence shared as
23
+ * `local` changes (`null` or absent: nothing shared from here yet). `local` is compared by value,
24
+ * so a kit may build it anew on every render.
25
+ */
26
+ export declare function usePresence(host: HostConnection, local?: KitPresence | null): {
27
+ available: boolean;
28
+ peers: KitPeerPresence[];
29
+ setPresence: (presence: KitPresence) => void;
30
+ };
31
+ /** A rectangle in the kit's own coordinates (document points, or the canvas's), as the kit places objects. */
32
+ export type PresenceRect = {
33
+ x: number;
34
+ y: number;
35
+ width: number;
36
+ height: number;
37
+ };
38
+ /** One object a peer has selected, where the kit found it. `label` is true for the first of the peer's objects: draw their name there. */
39
+ export type RemoteSelection = {
40
+ principal: string;
41
+ name: string;
42
+ color: string;
43
+ objectId: string;
44
+ rect: PresenceRect;
45
+ label: boolean;
46
+ };
47
+ /** A peer's caret, where the kit found it (a thin rectangle at the caret's position). */
48
+ export type RemoteCaret = {
49
+ principal: string;
50
+ name: string;
51
+ color: string;
52
+ caret: KitPresenceCaret;
53
+ rect: PresenceRect;
54
+ };
55
+ /**
56
+ * The peers' selected objects the kit can place: `locate` answers an object's rectangle, or
57
+ * `null` for one it does not show now (on another page, deleted meanwhile), which is left out.
58
+ */
59
+ export declare function remoteSelections(peers: readonly KitPeerPresence[], locate: (objectId: string) => PresenceRect | null): RemoteSelection[];
60
+ /** The peers' carets the kit can place (`locate` answers `null` for one it does not show now). */
61
+ export declare function remoteCarets(peers: readonly KitPeerPresence[], locate: (caret: KitPresenceCaret) => PresenceRect | null): RemoteCaret[];
62
+ /** `remoteSelections`, kept while `peers` and `locate` stay the same (memoize `locate`). */
63
+ export declare function useRemoteSelections(peers: readonly KitPeerPresence[], locate: (objectId: string) => PresenceRect | null): RemoteSelection[];
64
+ /** `remoteCarets`, kept while `peers` and `locate` stay the same (memoize `locate`). */
65
+ export declare function useRemoteCarets(peers: readonly KitPeerPresence[], locate: (caret: KitPresenceCaret) => PresenceRect | null): RemoteCaret[];
66
+ /** A peer's color, or a neutral one when the host named none. */
67
+ export declare const peerColor: (color: string) => string;
68
+ /**
69
+ * Draws the peers' selections (an outline in each peer's color, their name in a tag above the
70
+ * first object) and carets on a 2D canvas, for a kit that draws its overlays there. `toScreen`
71
+ * maps the kit's coordinates to the canvas's, as kit-editor's `RasterDecoration` hands it.
72
+ */
73
+ export declare function drawPresence(context: CanvasRenderingContext2D, items: {
74
+ selections?: readonly RemoteSelection[];
75
+ carets?: readonly RemoteCaret[];
76
+ }, toScreen: (x: number, y: number) => {
77
+ x: number;
78
+ y: number;
79
+ }): void;
@@ -0,0 +1,6 @@
1
+ /**
2
+ * A kit's interface strings by locale (protocol section 4): `en-US` is required, the rest
3
+ * optional. Lookups fall back from `zh-CN` to `zh` to `en-US`, then to the key itself.
4
+ */
5
+ export type Catalog = Record<string, string>;
6
+ export declare function createStrings(catalogs: Record<string, Catalog>, locale: string): (key: string, values?: Record<string, string | number>) => string;
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Icons for the engines' tools and commands. The kit engines name their tool icons `tool-<kind>`
3
+ * (`EngineToolInfo.icon`); each kind maps to the closest Tessera icon, and an unknown one to a
4
+ * generic shape. A command has no icon of its own: one is chosen from the words in its id and
5
+ * title, with a generic icon when none matches, so a ribbon built from commands is never a wall of
6
+ * bare labels.
7
+ */
8
+ import { type IconComponent } from '@kition/tessera-icons/react';
9
+ /**
10
+ * The icon for an engine tool's icon name (`tool-line`). With the tool's `id`, tools that share an
11
+ * icon name (CAD's `dimlinear`, `dimaligned`, and `dimradius`) get their own icons.
12
+ */
13
+ export declare function toolIcon(name: string, id?: string): IconComponent;
14
+ /**
15
+ * The icon of a command nothing matches: a neutral mark that claims no meaning (it used to be the
16
+ * selection tool's icon, which made unknown commands read as Select).
17
+ */
18
+ export declare const COMMAND_FALLBACK_ICON: IconComponent;
19
+ /**
20
+ * A kit's own icons for its commands, by command id: they win over every rule. A kit registers
21
+ * them once, when its editor loads, for the commands the rules cannot read (CAD's `dimaligned`,
22
+ * Film's `transcript.generate`).
23
+ */
24
+ export declare function registerCommandIcons(icons: Readonly<Record<string, IconComponent>>): void;
25
+ /**
26
+ * An icon for an engine command: the kit's own (`registerCommandIcons`), else by its verb, then
27
+ * by its object, then by the specific words of `COMMAND_ICONS`; the neutral mark when none match.
28
+ */
29
+ export declare function commandIcon(command: {
30
+ id: string;
31
+ title?: string | null;
32
+ }): IconComponent;
@@ -0,0 +1,59 @@
1
+ /**
2
+ * A kit editor's elements (protocol section 9, `ui/elements`). Commands and menus come from the
3
+ * engine; tools, panels, ribbon tabs and groups, and a kit's own controls are declared with
4
+ * `defineKitUi`, because closed menus and inactive tabs are never rendered to be found.
5
+ */
6
+ import type { KitUiElement } from '@kition/kit-ui-protocol';
7
+ import type { KitCommand } from './engine/kitModule.js';
8
+ import { type UiConfig } from './uiConfig.js';
9
+ /** A declared element: its full id (`panel:layers`), a key the kit's strings translate, and the element it sits in. */
10
+ export type KitUiItem = {
11
+ id: string;
12
+ label: string;
13
+ parent?: string;
14
+ };
15
+ /** One row of an upstream-style menu catalog; `command: "---"` is a separator, and a `kit:` command is the kit's own. */
16
+ export type MenuRow = {
17
+ path: readonly string[];
18
+ label: string;
19
+ shortcut?: string | null;
20
+ command: string;
21
+ };
22
+ /**
23
+ * A kit's elements. `menus` is the menu catalog the kit passes to `catalogTabs`, so its menus, commands,
24
+ * and kit rows are listed even while closed.
25
+ */
26
+ export type KitUiDeclaration = {
27
+ tools?: KitUiItem[];
28
+ panels?: KitUiItem[];
29
+ tabs?: KitUiItem[];
30
+ groups?: KitUiItem[];
31
+ controls?: KitUiItem[];
32
+ menus?: readonly MenuRow[];
33
+ };
34
+ /** The prefix of a catalog row the kit runs itself (Window toggles, Help). */
35
+ export declare const KIT_COMMAND_PREFIX = "kit:";
36
+ /** A catalog row's element id: `control:<name>` for a `kit:<name>` row, `command:<id>` for an engine row. */
37
+ export declare function catalogRowId(command: string): string;
38
+ /** A kit's elements, declared once next to its `connectHost` call. */
39
+ export declare function defineKitUi(declaration: KitUiDeclaration): KitUiDeclaration;
40
+ /** The document actions every shell draws, labeled with the shell's own strings. */
41
+ export declare const DOCUMENT_ACTIONS: KitUiItem[];
42
+ /** Every id a kit declared, with the document actions; null when it declared nothing (no warnings then). */
43
+ export declare function declaredIds(declaration: KitUiDeclaration | null): ReadonlySet<string> | null;
44
+ export type CatalogInput = {
45
+ commands: readonly KitCommand[];
46
+ declaration: KitUiDeclaration | null;
47
+ /** The engine's own tools (engine-tools capability), by their engine ids. */
48
+ engineTools: ReadonlyArray<{
49
+ id: string;
50
+ label: string;
51
+ }>;
52
+ /** Whether the host has an agent (capability `agent`): without one, Ask Agent is not an element. */
53
+ agent: boolean;
54
+ t: (key: string) => string;
55
+ phrase: (english: string) => string;
56
+ config: UiConfig;
57
+ };
58
+ /** The editor's elements in declared menu catalog, engine menu and command, tool, declared, action order; each id once (the first listing wins). */
59
+ export declare function buildCatalog({ commands, declaration, engineTools, agent, t, phrase, config }: CatalogInput): KitUiElement[];
@@ -0,0 +1,53 @@
1
+ /**
2
+ * The UI configuration (Kit UI protocol section 9): which elements the host hides or disables,
3
+ * the buttons it adds, and what the person hid. Pure functions over element ids such as
4
+ * `command:image.crop`, `menu:Filter/Blur`, and `panel:layers`.
5
+ */
6
+ import { KitRpcError, type KitUiHostButton } from '@kition/kit-ui-protocol';
7
+ import type { KitCommand } from './engine/kitModule.js';
8
+ import { type ModeRules } from './frame/modes.js';
9
+ /** A parsed configuration: every list present, every entry valid. `personal` is the person's hides; `modes` the display modes the host allows and presets. */
10
+ export type UiConfig = {
11
+ hide: string[];
12
+ disable: string[];
13
+ add: KitUiHostButton[];
14
+ personal: string[];
15
+ modes: ModeRules;
16
+ };
17
+ export declare const EMPTY_UI_CONFIG: UiConfig;
18
+ type Warn = (message: string) => void;
19
+ /** A configuration from the host, entry by entry: invalid ones are dropped with a warning (UI-C4). */
20
+ export declare function parseUiConfig(raw: unknown, warn?: Warn): UiConfig;
21
+ /** Whether `pattern` names `id`: the same id, or a prefix ending in `*`. */
22
+ export declare function matches(pattern: string, id: string): boolean;
23
+ /** The ids an element answers to: its own, every menu above it (a command or a menu), and its action. */
24
+ export declare function idsFor(id: string, menu?: readonly string[]): string[];
25
+ /** The More menu: the person's only way back to Customize, so a personal hide never hides it. */
26
+ export declare const MORE_ACTION = "action:more";
27
+ /**
28
+ * An element's state: `hidden` (not drawn), `disabled` (drawn greyed), and `denied` (refused on
29
+ * every path, UI-C2; only the host's configuration denies). A host hide counts before a personal
30
+ * one, and a personal hide never covers `action:more`.
31
+ */
32
+ export type UiState = {
33
+ hostHidden: boolean;
34
+ hostDisabled: boolean;
35
+ personalHidden: boolean;
36
+ hidden: boolean;
37
+ disabled: boolean;
38
+ denied: boolean;
39
+ };
40
+ export declare function uiState(config: UiConfig, id: string, menu?: readonly string[]): UiState;
41
+ /** The host buttons at `place`, in the host's order. */
42
+ export declare function buttonsAt(config: UiConfig, place: string): KitUiHostButton[];
43
+ /** A host button's label for `locale`: the exact tag, its language, `en-US`, then the id (own keys only, so `constructor` is no label). */
44
+ export declare function buttonLabel(item: KitUiHostButton, locale: string): string;
45
+ /** The error a refused command answers with (UI-C2). `step` names the `ai/run` step, in the message and the data. */
46
+ export declare function notAllowed(command: string, step?: number): KitRpcError;
47
+ /** The first `ai/run` step the configuration refuses, or -1 (UI-C6). */
48
+ export declare function refusedStep(config: UiConfig, steps: ReadonlyArray<{
49
+ command: string;
50
+ }>, menuOf: (id: string) => readonly string[]): number;
51
+ /** The commands an agent may see: without host-hidden ones, host-disabled ones not enabled (UI-C2). */
52
+ export declare function agentCommands(config: UiConfig, commands: readonly KitCommand[]): KitCommand[];
53
+ export {};
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The UI configuration where a kit's editor draws (protocol section 9). The editor provider
3
+ * gives it (`UiProvider`); `KitElement` and Kition Tessera's components ask it whether an element
4
+ * is hidden or disabled, Tessera's through its `ElementsProvider`, which `UiProvider` fills.
5
+ */
6
+ import { type ReactNode } from 'react';
7
+ import type { KitUiHostButton } from '@kition/kit-ui-protocol';
8
+ import { type UiStore } from './uiStore.js';
9
+ export type UiContextValue = {
10
+ store: UiStore;
11
+ locale: string;
12
+ /** A command's menu path (`menu:` configuration). */
13
+ menuOf: (command: string) => readonly string[];
14
+ /** The kit's declared ids (development warnings); null when it declared none. */
15
+ declared: ReadonlySet<string> | null;
16
+ /** A host button was pressed. */
17
+ press: (id: string) => void;
18
+ /** Offers "Hide" for an element at a screen point; null without the `customize` capability. */
19
+ offerHide: ((id: string, x: number, y: number) => void) | null;
20
+ /** Opens the customize dialog; null without the `customize` capability. */
21
+ openCustomize: (() => void) | null;
22
+ /** Hides an element for the person at once; null without the `customize` capability. */
23
+ hide: ((id: string) => void) | null;
24
+ /** Draws the host's buttons at a place (the editor gives `HostButtons`; `ui.tsx` cannot import it). */
25
+ renderButtons: (place: string, as: 'menu' | 'ribbon' | 'action') => ReactNode;
26
+ /**
27
+ * Whether the session hides an engine command whatever the configuration says: a commenter's
28
+ * editor hides the edits they cannot run (`hiddenForCommenter`). Absent: it hides none.
29
+ */
30
+ sessionHidden?: (command: string) => boolean;
31
+ };
32
+ export declare const UiContext: import("react").Context<UiContextValue | null>;
33
+ /**
34
+ * The configuration here, and what it says about an element (nothing hidden outside an editor).
35
+ * Depend on `config` in effects; the functions are rebuilt each render.
36
+ */
37
+ export declare function useUi(): {
38
+ config: import("./uiConfig.js").UiConfig;
39
+ store: UiStore;
40
+ locale: string;
41
+ declared: ReadonlySet<string> | null;
42
+ state: (id: string, menu?: readonly string[]) => import("./uiConfig.js").UiState;
43
+ sessionHidden: (command: string) => boolean;
44
+ buttons: (place: string) => KitUiHostButton[];
45
+ press: (id: string) => void;
46
+ offerHide: ((id: string, x: number, y: number) => void) | null;
47
+ openCustomize: (() => void) | null;
48
+ hide: ((id: string) => void) | null;
49
+ renderButtons: (place: string, as: "menu" | "ribbon" | "action") => ReactNode;
50
+ };
51
+ /** In development, warns once about an id drawn without being declared with `defineKitUi`. */
52
+ export declare function warnUndeclared(id: string, declared: ReadonlySet<string> | null): void;
53
+ /**
54
+ * Gives a UI configuration to everything below: kit-editor's own parts (`useUi`) and Tessera's
55
+ * components, which see it as element states and draw the host's buttons as extras.
56
+ */
57
+ export declare function UiProvider({ value, children }: {
58
+ value: UiContextValue | null;
59
+ children: ReactNode;
60
+ }): import("react").JSX.Element;
61
+ /** One of the kit's own elements: not drawn when hidden; its form controls disabled when disabled (enforcement is in the session's run). */
62
+ export declare function KitElement({ id, children }: {
63
+ id: string;
64
+ children: ReactNode;
65
+ }): import("react").JSX.Element | null;