@whity/ui 0.0.0-stage → 1.0.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 (205) hide show
  1. package/README.md +106 -2
  2. package/package.json +219 -4
  3. package/src/access-denied.stories.tsx +179 -0
  4. package/src/access-denied.tsx +305 -0
  5. package/src/action-proposal.tsx +338 -0
  6. package/src/actor-chip.tsx +71 -0
  7. package/src/agent-activity.tsx +163 -0
  8. package/src/agent-collaboration.stories.tsx +156 -0
  9. package/src/agent-run-status.tsx +196 -0
  10. package/src/alert-dialog.stories.tsx +45 -0
  11. package/src/alert-dialog.tsx +147 -0
  12. package/src/alert.stories.tsx +91 -0
  13. package/src/alert.tsx +89 -0
  14. package/src/app-sidebar.stories.tsx +195 -0
  15. package/src/app-sidebar.tsx +604 -0
  16. package/src/approval-queue.tsx +109 -0
  17. package/src/audience-group-picker.stories.tsx +198 -0
  18. package/src/audience-group-picker.tsx +362 -0
  19. package/src/audience-people-picker.stories.tsx +102 -0
  20. package/src/audience-people-picker.tsx +279 -0
  21. package/src/avatar-pattern.ts +138 -0
  22. package/src/avatar.tsx +125 -0
  23. package/src/badge.stories.tsx +105 -0
  24. package/src/badge.tsx +68 -0
  25. package/src/beta-warning.stories.tsx +79 -0
  26. package/src/beta-warning.tsx +189 -0
  27. package/src/bilingual-input.stories.tsx +82 -0
  28. package/src/bilingual-input.tsx +188 -0
  29. package/src/board.tsx +216 -0
  30. package/src/breadcrumb.stories.tsx +51 -0
  31. package/src/breadcrumb.tsx +90 -0
  32. package/src/built-on-whity.tsx +52 -0
  33. package/src/button.stories.tsx +87 -0
  34. package/src/button.tsx +123 -0
  35. package/src/card.stories.tsx +423 -0
  36. package/src/card.tsx +180 -0
  37. package/src/chart.stories.tsx +66 -0
  38. package/src/chart.tsx +228 -0
  39. package/src/checkbox.stories.tsx +62 -0
  40. package/src/checkbox.tsx +54 -0
  41. package/src/collapsible.stories.tsx +48 -0
  42. package/src/collapsible.tsx +34 -0
  43. package/src/color-card.stories.tsx +61 -0
  44. package/src/color-card.tsx +270 -0
  45. package/src/color-picker.stories.tsx +65 -0
  46. package/src/color-picker.tsx +425 -0
  47. package/src/column-matcher.tsx +84 -0
  48. package/src/command-palette.tsx +398 -0
  49. package/src/confirm-action.tsx +98 -0
  50. package/src/copy-block.stories.tsx +38 -0
  51. package/src/copy-block.tsx +85 -0
  52. package/src/data-table.stories.tsx +200 -0
  53. package/src/data-table.tsx +1686 -0
  54. package/src/date-picker.stories.tsx +61 -0
  55. package/src/date-picker.tsx +456 -0
  56. package/src/design-cards.stories.tsx +551 -0
  57. package/src/dialog.stories.tsx +48 -0
  58. package/src/dialog.tsx +179 -0
  59. package/src/display-preferences.tsx +50 -0
  60. package/src/documents/barcode-svg.stories.tsx +72 -0
  61. package/src/documents/barcode-svg.tsx +79 -0
  62. package/src/dropdown-menu.stories.tsx +77 -0
  63. package/src/dropdown-menu.tsx +271 -0
  64. package/src/editor/agent-panel.tsx +222 -0
  65. package/src/editor/agents.stories.tsx +81 -0
  66. package/src/editor/agents.ts +55 -0
  67. package/src/editor/behaviour.ts +279 -0
  68. package/src/editor/block-ids.ts +44 -0
  69. package/src/editor/block-list.tsx +104 -0
  70. package/src/editor/block-toolbar.tsx +490 -0
  71. package/src/editor/bubble.tsx +119 -0
  72. package/src/editor/catalogue.ts +169 -0
  73. package/src/editor/collab-rail.tsx +746 -0
  74. package/src/editor/collab.stories.tsx +207 -0
  75. package/src/editor/collab.ts +87 -0
  76. package/src/editor/contract.ts +476 -0
  77. package/src/editor/convert.ts +414 -0
  78. package/src/editor/doc-editor.stories.tsx +98 -0
  79. package/src/editor/doc-editor.tsx +1492 -0
  80. package/src/editor/editor.css +636 -0
  81. package/src/editor/extensions.ts +86 -0
  82. package/src/editor/field-bar.tsx +154 -0
  83. package/src/editor/field-picker.tsx +109 -0
  84. package/src/editor/fields.ts +100 -0
  85. package/src/editor/gutter.tsx +443 -0
  86. package/src/editor/index.ts +23 -0
  87. package/src/editor/label-sheet.tsx +289 -0
  88. package/src/editor/labels.ts +394 -0
  89. package/src/editor/link-tools.tsx +141 -0
  90. package/src/editor/node-views.tsx +461 -0
  91. package/src/editor/page-view.tsx +372 -0
  92. package/src/editor/phone.tsx +310 -0
  93. package/src/editor/plugin-block-view.tsx +230 -0
  94. package/src/editor/plugin-blocks.stories.tsx +96 -0
  95. package/src/editor/plugin-blocks.ts +52 -0
  96. package/src/editor/publish-check.tsx +201 -0
  97. package/src/editor/rich-blocks.stories.tsx +146 -0
  98. package/src/editor/sample.ts +40 -0
  99. package/src/editor/save-block-dialog.tsx +141 -0
  100. package/src/editor/saved-block-view.tsx +205 -0
  101. package/src/editor/saved-blocks.stories.tsx +105 -0
  102. package/src/editor/saved-parts.ts +192 -0
  103. package/src/editor/schema-rich.ts +156 -0
  104. package/src/editor/schema.ts +368 -0
  105. package/src/editor/services.tsx +205 -0
  106. package/src/editor/slash.ts +64 -0
  107. package/src/editor/suggesting.ts +372 -0
  108. package/src/editor/suggestions.ts +763 -0
  109. package/src/editor/table-keys.ts +66 -0
  110. package/src/editor/templates.stories.tsx +324 -0
  111. package/src/editor/toolbar.tsx +364 -0
  112. package/src/empty-state.stories.tsx +51 -0
  113. package/src/empty-state.tsx +126 -0
  114. package/src/empty-state.usage-notes.md +30 -0
  115. package/src/form.stories.tsx +112 -0
  116. package/src/form.tsx +176 -0
  117. package/src/globals.css +20 -0
  118. package/src/icon-button.tsx +85 -0
  119. package/src/icon-map.ts +335 -0
  120. package/src/icon.tsx +41 -0
  121. package/src/index.ts +90 -0
  122. package/src/input.stories.tsx +157 -0
  123. package/src/input.tsx +768 -0
  124. package/src/kpi-strip.tsx +47 -0
  125. package/src/localized-text.ts +76 -0
  126. package/src/locked-screen.stories.tsx +29 -0
  127. package/src/locked-screen.tsx +75 -0
  128. package/src/lockup.tsx +42 -0
  129. package/src/lottie.tsx +441 -0
  130. package/src/mark.tsx +62 -0
  131. package/src/math-text.stories.tsx +33 -0
  132. package/src/math-text.tsx +43 -0
  133. package/src/menu-bar.stories.tsx +198 -0
  134. package/src/menu-bar.tsx +373 -0
  135. package/src/message-thread.tsx +181 -0
  136. package/src/money/currency.ts +244 -0
  137. package/src/money/money-input.tsx +131 -0
  138. package/src/money/money.tsx +33 -0
  139. package/src/open-on-computer.tsx +150 -0
  140. package/src/otp-input.tsx +161 -0
  141. package/src/page-header.stories.tsx +95 -0
  142. package/src/page-header.tsx +122 -0
  143. package/src/page-shell.stories.tsx +42 -0
  144. package/src/page-shell.tsx +32 -0
  145. package/src/page-states.tsx +277 -0
  146. package/src/pagination.stories.tsx +45 -0
  147. package/src/pagination.tsx +98 -0
  148. package/src/paper-sheet.stories.tsx +88 -0
  149. package/src/paper-sheet.tsx +85 -0
  150. package/src/phone-tab-bar.tsx +152 -0
  151. package/src/plugin-card.stories.tsx +208 -0
  152. package/src/plugin-card.tsx +931 -0
  153. package/src/popover.stories.tsx +48 -0
  154. package/src/popover.tsx +55 -0
  155. package/src/radio-group.stories.tsx +26 -0
  156. package/src/radio-group.tsx +44 -0
  157. package/src/route-flow/editor.tsx +1087 -0
  158. package/src/route-flow/model.ts +771 -0
  159. package/src/save-bar.tsx +94 -0
  160. package/src/scope-grant.tsx +139 -0
  161. package/src/screen-too-small.stories.tsx +61 -0
  162. package/src/screen-too-small.tsx +104 -0
  163. package/src/search-field.tsx +65 -0
  164. package/src/select.stories.tsx +44 -0
  165. package/src/select.tsx +197 -0
  166. package/src/separator.stories.tsx +34 -0
  167. package/src/separator.tsx +34 -0
  168. package/src/sheet.stories.tsx +49 -0
  169. package/src/sheet.tsx +168 -0
  170. package/src/skeleton.stories.tsx +28 -0
  171. package/src/skeleton.tsx +19 -0
  172. package/src/slider.stories.tsx +78 -0
  173. package/src/slider.tsx +300 -0
  174. package/src/spinner.stories.tsx +33 -0
  175. package/src/spinner.tsx +55 -0
  176. package/src/stepper.tsx +85 -0
  177. package/src/switch.stories.tsx +42 -0
  178. package/src/switch.tsx +41 -0
  179. package/src/switcher.stories.tsx +111 -0
  180. package/src/switcher.tsx +131 -0
  181. package/src/system-state.tsx +55 -0
  182. package/src/table.stories.tsx +48 -0
  183. package/src/table.tsx +121 -0
  184. package/src/tabs.stories.tsx +74 -0
  185. package/src/tabs.tsx +90 -0
  186. package/src/tag-input.stories.tsx +67 -0
  187. package/src/tag-input.tsx +117 -0
  188. package/src/tenant-logo.tsx +63 -0
  189. package/src/tenant-switcher.stories.tsx +38 -0
  190. package/src/tenant-switcher.tsx +164 -0
  191. package/src/textarea.stories.tsx +27 -0
  192. package/src/textarea.tsx +18 -0
  193. package/src/theme-mode.ts +52 -0
  194. package/src/time-grid.tsx +163 -0
  195. package/src/time-picker.stories.tsx +62 -0
  196. package/src/time-picker.tsx +615 -0
  197. package/src/toggle-group.tsx +138 -0
  198. package/src/tooltip.stories.tsx +43 -0
  199. package/src/tooltip.tsx +73 -0
  200. package/src/top-nav.stories.tsx +58 -0
  201. package/src/top-nav.tsx +324 -0
  202. package/src/undo-bar.tsx +107 -0
  203. package/src/utils.ts +45 -0
  204. package/src/view-toggle.stories.tsx +84 -0
  205. package/src/view-toggle.tsx +110 -0
@@ -0,0 +1,476 @@
1
+ /**
2
+ * Whity document editor — the contract (design system 2.2, decisions E.1–E.47;
3
+ * 3.4 adds stable keys for a saved block's per-document parts, E.23a).
4
+ *
5
+ * The design system defines the editor; the Whity team builds it (E.1).
6
+ * This file is the shared vocabulary between the editor, Whity Render,
7
+ * agents (MCP tools) and plugins. Keep it framework-free: the editor maps
8
+ * it onto TipTap/ProseMirror nodes and marks (see README.md beside it).
9
+ */
10
+
11
+ /* ---------------------------------------------------------------- Ids */
12
+
13
+ export type BlockId = string; // stable, unique within a document (nanoid)
14
+ export type DocId = string;
15
+ export type UserId = string;
16
+ export type AgentId = string; // an AI principal
17
+ export type PluginId = string; // e.g. "com.example.delivery-tracker"
18
+ export type SavedBlockId = string;
19
+ /** E.23a: names one per-document part inside a saved block. Minted once ("pd_" + 8-char nanoid), never reused or renumbered. */
20
+ export type PerDocumentKey = string;
21
+ export type ISODateTime = string; // "2026-10-29T14:02:00Z"
22
+
23
+ /** Who did something. Agents always carry the person they act for (stage 7 actor chip, E.4). */
24
+ export type Actor =
25
+ | { kind: 'person'; id: UserId; name: string }
26
+ | { kind: 'agent'; id: AgentId; name: string; onBehalfOf: { id: UserId; name: string }; scope: string[] }
27
+ | { kind: 'system'; name: 'Whity' };
28
+
29
+ /* ----------------------------------------------------------- Document */
30
+
31
+ /** E.43: 'label' is a sheet of identical labels, printed one per record or CSV row; page view only. */
32
+ export type DocumentKind = 'template' | 'letter' | 'report' | 'note' | 'wiki' | 'label';
33
+
34
+ export interface WhityDocument {
35
+ id: DocId;
36
+ kind: DocumentKind;
37
+ title: string;
38
+ /** Text direction of the UI the document was created in; each block also follows its own text (E.33). */
39
+ lang: 'en' | 'ar';
40
+ /** E.7: templates and printed kinds open in the page view; notes and wiki continuous. */
41
+ defaultView: 'page' | 'continuous';
42
+ /** E.34 */
43
+ fullWidth?: boolean;
44
+ /** Page setup for the page view and Whity Render (stage 6). */
45
+ page?: { size: 'A4' | 'A5' | 'Letter'; marginMm: 16; letterhead: boolean };
46
+ /** E.43: label sheets only (A4 or Letter). Each label holds the document's blocks. */
47
+ labels?: LabelGrid;
48
+ /** For templates: the record type its fields come from, e.g. "invoice". */
49
+ recordType?: string;
50
+ /**
51
+ * A template's own fields, for values no record type provides (a CSV column
52
+ * on a label sheet). Each is the field `template.<key>`; with a record it prints blank.
53
+ */
54
+ ownFields?: OwnField[];
55
+ blocks: Block[];
56
+ comments: CommentThread[];
57
+ /** Open suggestions; their text and blocks carry `insertion`/`deletion` marks or a `suggestion` attr with the same id. */
58
+ suggestions: Suggestion[];
59
+ /** E.9: templates have a draft and a published version. */
60
+ status: 'draft' | 'published';
61
+ publishedVersion?: number;
62
+ /** E.44: the document's theme and its own overrides; absent or null follows the workspace default. */
63
+ theme?: DocumentThemeRef | null;
64
+ updatedAt: ISODateTime;
65
+ updatedBy: Actor;
66
+ }
67
+
68
+ /* ------------------------------------------------------------- Themes */
69
+
70
+ /** E.44, stage 6 (6.2): a workspace line the letterhead can print under the name. */
71
+ export type LetterheadLine = 'address' | 'taxId' | 'phone' | 'email';
72
+
73
+ /** A theme's tokens (DOCUMENT-THEMES.md 3.2). Every key is optional in a theme or an override. */
74
+ export interface DocumentThemeTokens {
75
+ /** The print colour as #rrggbb: the title, and H1-H3 with `title-and-headings` (E.45). */
76
+ accent?: string;
77
+ /** The title colour on screen in dark mode (E.11). Never printed. */
78
+ accentOnDark?: string;
79
+ accentUse?: 'title' | 'title-and-headings';
80
+ letterhead?: {
81
+ logo?: 'wide' | 'square' | 'none';
82
+ /** In this order, without repeats, at most four. */
83
+ lines?: LetterheadLine[];
84
+ /** FP.3: how the letterhead is laid out. */
85
+ layout?: 'start' | 'centred' | 'bilingual';
86
+ };
87
+ /** FP.2–FP.10: how form responses print. Anything but the standard needs a paid plan or a trial. */
88
+ form?: FormPrintoutStyle;
89
+ }
90
+
91
+ /** FP.2–FP.10 (3.4). Every key optional; missing keys take the standard layout. */
92
+ export interface FormPrintoutStyle {
93
+ header?: 'letterhead' | 'centred' | 'bilingual';
94
+ officeDetails?: 'decisionLine' | 'strip';
95
+ decision?: 'topAndEnd' | 'top' | 'end';
96
+ /** A number, B the Whity mark (free workspaces always), C eyebrow, D rail, E tab, F plane. */
97
+ sectionStyle?: 'number' | 'mark' | 'eyebrow' | 'rail' | 'tab' | 'plane';
98
+ questions?: 'stacked' | 'twoColumns';
99
+ longAnswers?: 'countAndContinued' | 'plain';
100
+ /** More than 8 options always print the chosen only. */
101
+ choices?: 'allOptions' | 'chosenOnly';
102
+ yesNo?: 'word' | 'threeColumns';
103
+ empty?: 'collapseAndMark' | 'hide' | 'printAll';
104
+ signatures?: 'confirmedAndDrawn' | 'confirmedOnly' | 'withPaperLines';
105
+ approvals?: 'list' | 'cards';
106
+ footer?: { reference?: boolean; marks?: boolean; qrEveryPage?: boolean };
107
+ /** Theme images printed at the footer's end side (ISO, accreditation), at most 3, 8 mm tall. */
108
+ marks?: { src: string; alt: string }[];
109
+ }
110
+
111
+ /** What a document stores: the theme it names and its overrides of the print colour and letterhead. */
112
+ export interface DocumentThemeRef {
113
+ /** 'whity.standard' | '<plugin>.<key>' | 'tenant.<key>' */
114
+ ref?: string;
115
+ overrides?: Pick<DocumentThemeTokens, 'accent' | 'letterhead'>;
116
+ }
117
+
118
+ /** Every token resolved: what the editor and Whity Render use. */
119
+ export interface ResolvedThemeTokens {
120
+ accent: string;
121
+ accentOnDark: string;
122
+ accentUse: 'title' | 'title-and-headings';
123
+ letterhead: { logo: 'wide' | 'square' | 'none'; lines: LetterheadLine[] };
124
+ }
125
+
126
+ /** The server's resolution of a document's theme (`resolvedTheme`). */
127
+ export interface ResolvedDocumentTheme {
128
+ /** The theme actually used, after falling back past one that isn't available. */
129
+ ref: string;
130
+ version: number;
131
+ hash: string;
132
+ tokens: ResolvedThemeTokens;
133
+ /** Where each token came from, by its path. */
134
+ sources: Record<string, string>;
135
+ /** What changed on the way, such as a print colour darkened to read on white. */
136
+ adjustments: { code: string; token: string; from: string; to?: string; message: string }[];
137
+ }
138
+
139
+ /* ------------------------------------------------------------- Inline */
140
+
141
+ /** Rich text inside a block: a list of runs. */
142
+ export type Inline = Text | FieldRef | HardBreak | MathRef;
143
+
144
+ export interface Text { type: 'text'; text: string; marks?: Mark[] }
145
+ export interface HardBreak { type: 'break' }
146
+ /** E.42: an inline formula in TeX, rendered with KaTeX; one character for the caret. */
147
+ export interface MathRef { type: 'math'; tex: string }
148
+
149
+ /** E.26: a merge field. One character for the caret; shows its label while editing, its value in preview. */
150
+ export interface FieldRef {
151
+ type: 'field';
152
+ path: string; // "customer.name", "invoice.total", "today"
153
+ label: string; // "Customer name"
154
+ /** E.27: required fields block issuing; fiscal fields are always required. */
155
+ required?: boolean;
156
+ /** E.23, E.23a: inside a synced saved block, filled per document. Names the part by its stable key. */
157
+ perDocument?: PerDocumentKey;
158
+ marks?: Mark[];
159
+ }
160
+
161
+ export type Mark =
162
+ | { type: 'bold' } // weight 600, never 700
163
+ | { type: 'italic' }
164
+ | { type: 'underline' }
165
+ | { type: 'strike' }
166
+ | { type: 'code' }
167
+ | { type: 'link'; href: string; recordRef?: RecordRef }
168
+ | { type: 'highlight' } // E.25: one colour
169
+ | { type: 'comment'; threadId: string }
170
+ | { type: 'insertion'; suggestionId: string } // E.4, part 6
171
+ | { type: 'deletion'; suggestionId: string }
172
+ | { type: 'perDocument'; key: PerDocumentKey }; // E.23a: text filled per document in a synced block; adjacent text with the same key is one part
173
+
174
+ /* ------------------------------------------------------------- Blocks */
175
+
176
+ interface BlockBase {
177
+ id: BlockId;
178
+ /** A block an agent or a suggesting person added: dashed until accepted (E.4). */
179
+ suggestion?: { id: string; action: 'insert' | 'delete' | 'move' };
180
+ }
181
+
182
+ export type Block =
183
+ | ParagraphBlock | HeadingBlock | QuoteBlock | CodeBlock
184
+ | ListItemBlock | ChecklistBlock | CalloutBlock
185
+ | ToggleBlock | ColumnsBlock | DividerBlock | PageBreakBlock
186
+ | TableBlock | ImageBlock | FileBlock
187
+ | RecordBlock | ChartBlock | SignatureBlock
188
+ | BarcodeBlock | QrBlock | MathBlock
189
+ | SavedBlockRef | PluginBlock;
190
+
191
+ export interface ParagraphBlock extends BlockBase { type: 'paragraph'; content: Inline[] }
192
+ export interface HeadingBlock extends BlockBase { type: 'heading'; level: 1 | 2 | 3; content: Inline[] }
193
+ export interface QuoteBlock extends BlockBase { type: 'quote'; content: Inline[] }
194
+ export interface CodeBlock extends BlockBase { type: 'code'; language?: string; text: string }
195
+ /** Lists are flat items with a level (0–2), like Notion; numbering restarts after any other block. */
196
+ export interface ListItemBlock extends BlockBase { type: 'bullet' | 'number'; level: 0 | 1 | 2; content: Inline[] }
197
+ export interface ChecklistBlock extends BlockBase { type: 'checklist'; level: 0 | 1 | 2; checked: boolean; content: Inline[] }
198
+ /** E.14: two kinds only. */
199
+ export interface CalloutBlock extends BlockBase { type: 'callout'; kind: 'note' | 'important'; content: Inline[] }
200
+ export interface ToggleBlock extends BlockBase { type: 'toggle'; open: boolean; summary: Inline[]; children: Block[] }
201
+ export interface ColumnsBlock extends BlockBase { type: 'columns'; columns: [Block[], Block[]] }
202
+ export interface DividerBlock extends BlockBase { type: 'divider' }
203
+ export interface PageBreakBlock extends BlockBase { type: 'pageBreak' }
204
+ /** E.15: document tables, not databases. */
205
+ export interface TableBlock extends BlockBase {
206
+ type: 'table';
207
+ headerRow: boolean;
208
+ columns: { align: 'start' | 'end'; widthPct?: number }[];
209
+ rows: Inline[][][]; // rows → cells → inline
210
+ }
211
+ export interface ImageBlock extends BlockBase { type: 'image'; src: string; alt: string; width: 'half' | 'wide' | 'full'; caption?: Inline[] }
212
+ export interface FileBlock extends BlockBase { type: 'file'; fileId: string; name: string; size: number; mime: string }
213
+
214
+ export interface RecordRef { type: string; id: string } // { type: 'invoice', id: 'INV-1042' }
215
+ /** E.16: live in the editor; each PDF freezes the values at render time. */
216
+ export interface RecordBlock extends BlockBase { type: 'record'; ref: RecordRef; view: 'card' | 'summary' }
217
+ export interface ChartBlock extends BlockBase {
218
+ type: 'chart';
219
+ chart: 'bar' | 'line' | 'donut';
220
+ /** A saved query or report the chart reads from; resolved within the reader's permissions. */
221
+ source: { query: string; params?: Record<string, string> };
222
+ title?: string;
223
+ }
224
+ /** Stage 6 signature row: signers, a date, an optional stamp. */
225
+ export interface SignatureBlock extends BlockBase {
226
+ type: 'signature';
227
+ signers: { name: Inline[]; role: Inline[] }[];
228
+ date: Inline[];
229
+ stamp: boolean;
230
+ }
231
+
232
+ /** E.40: ink only; the value is typed text or a merge field. Sized in mm in the page view. */
233
+ export interface BarcodeBlock extends BlockBase {
234
+ type: 'barcode';
235
+ symbology: 'code128' | 'ean13' | 'code39';
236
+ value: (Text | FieldRef)[];
237
+ showText: boolean;
238
+ widthMm?: number;
239
+ heightMm?: number;
240
+ }
241
+ /** E.41: a value or field as a QR. Not the document's verification QR (6.7), which stays automatic. */
242
+ export interface QrBlock extends BlockBase {
243
+ type: 'qr';
244
+ value: (Text | FieldRef)[];
245
+ caption?: Inline[];
246
+ sizeMm?: number;
247
+ }
248
+ /** E.42: a display formula in TeX, rendered with KaTeX on screen and in print. */
249
+ export interface MathBlock extends BlockBase { type: 'math'; tex: string }
250
+
251
+ /** A field a template declares itself: `key` is lowercase letters, digits and _. */
252
+ export interface OwnField {
253
+ key: string;
254
+ label: string;
255
+ sample?: string;
256
+ }
257
+
258
+ /** E.43: the grid of a label sheet. A certificate is a one-label sheet (columns 1, rows 1). */
259
+ export interface LabelGrid {
260
+ columns: number;
261
+ rows: number;
262
+ size: { widthMm: number; heightMm: number };
263
+ /** Between columns, and between rows unless `gapYMm` is set. */
264
+ gapMm: number;
265
+ /** Between rows, when stock differs from its column gap (Avery L7160: 2.5 and 0). */
266
+ gapYMm?: number;
267
+ }
268
+ /**
269
+ * E.43: what Print fills the labels from: one label per record, or per row of a CSV.
270
+ * The CSV travels with the print request and is never stored: a mailing list is
271
+ * personal data, and documents' file store holds only PDFs and images.
272
+ */
273
+ export type LabelPrintSource =
274
+ | { kind: 'records'; records: RecordRef[] }
275
+ | { kind: 'csv'; file: File; columns: Record<string, string> /* CSV column -> field path */ };
276
+
277
+ /** E.21: a saved block in a document. Synced ones point at the library; copies are ordinary blocks. */
278
+ export interface SavedBlockRef extends BlockBase {
279
+ type: 'savedBlock';
280
+ savedBlockId: SavedBlockId;
281
+ /** The library version this document shows; published templates pick up changes at their next publish. */
282
+ version: number;
283
+ /**
284
+ * E.23a: values for the parts filled per document, by the part's stable key (never by position).
285
+ * A key the library version no longer has is kept here, ignored, and reported (`orphanedParts`), so
286
+ * moving back to an older version or undoing a removal restores the value.
287
+ */
288
+ overrides: Partial<Record<PerDocumentKey, Inline[]>>;
289
+ }
290
+
291
+ /** E.17–E.19: a block from a plugin. The data is the plugin's own, validated against its schema. */
292
+ export interface PluginBlock extends BlockBase {
293
+ type: 'plugin';
294
+ plugin: PluginId;
295
+ blockType: string; // the plugin's block name, e.g. "deliveryStatus"
296
+ schemaVersion: number;
297
+ data: Record<string, unknown>;
298
+ }
299
+
300
+ /* ------------------------------------------- Comments and suggestions */
301
+
302
+ export interface CommentThread {
303
+ id: string;
304
+ /** Anchored by the `comment` mark; a thread whose text was deleted keeps its quote. */
305
+ quote: string;
306
+ messages: { id: string; by: Actor; at: ISODateTime; body: Inline[]; mentions: Actor[] }[];
307
+ resolved?: { by: Actor; at: ISODateTime };
308
+ }
309
+
310
+ export interface Suggestion {
311
+ id: string;
312
+ by: Actor; // a person in Suggesting mode, or an agent (E.4, E.10)
313
+ at: ISODateTime;
314
+ /** What the rail card says: "Replace 30 days with 14 days". Derived, but stored for the audit log. */
315
+ summary: string;
316
+ kind: 'text' | 'format' | 'block';
317
+ request?: string; // for agents: what they were asked
318
+ /** The one permission the change used, e.g. "document:edit" (shown on the card and in the audit log). */
319
+ permission?: string;
320
+ /** E.32: set when an owner's routine started it, not a person in the moment. */
321
+ routine?: { id: string; name: string; setUpBy: Actor & { kind: 'person' } };
322
+ }
323
+
324
+ /** E.29: anyone who can edit decides; every decision is logged. */
325
+ export interface SuggestionDecision { suggestionId: string; decision: 'accepted' | 'rejected'; by: Actor; at: ISODateTime }
326
+
327
+ /* --------------------------------------------- Block registry (plugins) */
328
+
329
+ /** What every block type declares, Whity's own and plugins' (E.17–E.20). */
330
+ export interface BlockDefinition {
331
+ /** Unique name; plugin blocks are namespaced: "com.example.delivery-tracker/deliveryStatus". */
332
+ name: string;
333
+ title: string; // "Delivery status"
334
+ description: string; // one line for the / menu
335
+ icon: string; // a Whity icon name or an SVG from the plugin
336
+ keywords?: string[];
337
+ /** The / menu group: Whity's groups, or the plugin's own name (E.20). */
338
+ group: 'Basic' | 'Lists' | 'Media' | 'Structure' | 'Whity' | string;
339
+ markdown?: string; // shortcut, e.g. "##"
340
+ /** JSON Schema for `data`; the editor validates before saving. */
341
+ schema: object;
342
+ defaultData: Record<string, unknown>;
343
+ /** Permissions the block reads with, granted at install and shown like ScopeGrant. */
344
+ scopes: string[];
345
+ /** E.17: how it renders. Verified and first-party: native; others: sandboxed frame. */
346
+ render: { native?: string /* module export using the Whity SDK */; sandbox?: { url: string; minHeight: number } };
347
+ /** E.18: needed to be used in templates or anything that prints. */
348
+ print?: { renderer: string /* Whity Render template id */ };
349
+ /** Controls for the block toolbar shown when the block is selected (E.8). */
350
+ toolbar?: { id: string; label: string; icon?: string; kind: 'toggle' | 'menu' | 'button' }[];
351
+ /** Where it may be inserted. */
352
+ allowedIn: DocumentKind[];
353
+ }
354
+
355
+ export interface PluginManifestBlocks {
356
+ plugin: PluginId;
357
+ name: string;
358
+ logo: string;
359
+ verified: boolean; // set by Whity, not the plugin
360
+ firstParty: boolean; // made by Whity; renders natively like verified ones (E.17)
361
+ blocks: BlockDefinition[];
362
+ }
363
+
364
+ /** E.19: the editor shows this when a block's plugin is off; the data is kept. */
365
+ export interface MissingPluginState { plugin: PluginId; pluginName: string; canEnable: boolean; blocksPublish: true }
366
+
367
+ /* -------------------------------------------------------- Saved blocks */
368
+
369
+ /**
370
+ * E.23a: one part of a synced saved block that each document fills (a signer's name, a date).
371
+ *
372
+ * Rules:
373
+ * - The key is minted when the creator marks the part ("Fill per document") and stays with it through
374
+ * edits, moves, reordering, version bumps and translation. Unmarking deletes the key; marking again mints a new one.
375
+ * - Keys are unique within a saved block. Copying a marked part inside the same block mints a new key;
376
+ * pasting it into another block or document drops the mark.
377
+ * - Text: every run carrying the `perDocument` mark with this key is the part. A merge field: `FieldRef.perDocument` holds the key.
378
+ * - Documents store values in `SavedBlockRef.overrides[key]`. Nothing is ever looked up by position.
379
+ */
380
+ export interface PerDocumentPart {
381
+ key: PerDocumentKey;
382
+ /** Shown in the "Fill in" prompt and the issuing bar: "Signer's name". English and Arabic. */
383
+ label: { en: string; ar?: string };
384
+ kind: 'text' | 'field';
385
+ /** Blocks issuing until filled, like E.27. */
386
+ required?: boolean;
387
+ /** Shown, dashed, until a document fills it. */
388
+ placeholder?: Inline[];
389
+ }
390
+
391
+ /** E.23a: what the editor reports when a document moves to a newer library version. */
392
+ export interface SavedBlockVersionChange {
393
+ savedBlockId: SavedBlockId;
394
+ from: number;
395
+ to: number;
396
+ /** Parts the new version added: empty in this document until filled. */
397
+ newParts: PerDocumentKey[];
398
+ /** Values this document holds for parts the new version removed. Kept, not printed. */
399
+ orphanedParts: PerDocumentKey[];
400
+ }
401
+
402
+ /** E.21–E.24 */
403
+ export interface SavedBlock {
404
+ id: SavedBlockId;
405
+ name: string;
406
+ description?: string;
407
+ mode: 'synced' | 'copy';
408
+ sharing: 'me' | 'workspace';
409
+ owner: Actor;
410
+ blocks: Block[];
411
+ /** E.23a: the parts filled per document, in reading order. Order is for display only; keys never change with it. */
412
+ perDocumentParts: PerDocumentPart[];
413
+ /** @deprecated 3.4: use `perDocumentParts`. Kept one release for reading old rows. */
414
+ perDocumentKeys?: PerDocumentKey[];
415
+ version: number;
416
+ usedIn?: number; // documents using a synced block
417
+ }
418
+
419
+ /* ---------------------------------------------------- The editor's API */
420
+
421
+ export type EditorMode = 'editing' | 'suggesting' | 'viewing'; // E.10
422
+
423
+ export interface AgentRequest {
424
+ agent: AgentId;
425
+ request: string; // what the person typed
426
+ /** E.31: the document and the records its fields and blocks point to. */
427
+ context: { document: DocId; records: RecordRef[]; selection?: { blockIds: BlockId[]; text: string } };
428
+ kind: 'write' | 'rewrite' | 'comment-reply';
429
+ }
430
+ export interface AgentResult {
431
+ by: Actor & { kind: 'agent' };
432
+ /** Always suggestions (E.4): inserted blocks, or insertion/deletion marks for a rewrite. */
433
+ blocks?: Block[];
434
+ rewrite?: { deleteText: string; insert: Inline[] };
435
+ comment?: Inline[];
436
+ summary: string;
437
+ }
438
+
439
+ export interface DocEditorProps {
440
+ document: WhityDocument;
441
+ me: Actor & { kind: 'person' };
442
+ canEdit: boolean; // false → Suggesting (E.10)
443
+ mode?: EditorMode; // defaults to 'editing', or 'suggesting' when canEdit is false
444
+ onModeChange?(mode: EditorMode): void;
445
+ view?: 'continuous' | 'page';
446
+ /** Field groups offered by the picker for this template's record type. */
447
+ fields: { group: string; items: { path: string; label: string; required?: boolean; sample?: string }[] }[];
448
+ /** E.12: preview with a record — read-only, comments and suggestions hidden, until showFields. */
449
+ preview?: { record: RecordRef; label: string; values: Record<string, string | null>; showFields?: boolean };
450
+ onPreviewChange?(preview: DocEditorProps['preview'] | null): void;
451
+ blockDefinitions: BlockDefinition[]; // Whity's and installed plugins'
452
+ savedBlocks: SavedBlock[];
453
+ agents: { id: AgentId; name: string; scope: string[] }[];
454
+ letterhead?: { logo?: string; name: string; lines: string[] };
455
+ onChange(doc: WhityDocument): void; // debounced; drafts autosave
456
+ onPublish?(doc: WhityDocument): Promise<void>; // E.9, templates only
457
+ onExportPdf?(doc: WhityDocument): Promise<void>; // Whity Render
458
+ onPrintLabels?(doc: WhityDocument, source: LabelPrintSource): Promise<void>; // E.43, label sheets only
459
+ onAskAgent?(req: AgentRequest): AsyncIterable<AgentResult>; // streams (part 7)
460
+ onDecide?(d: SuggestionDecision): void;
461
+ onSaveBlock?(b: Omit<SavedBlock, 'id' | 'version' | 'usedIn'>): Promise<SavedBlock>;
462
+ labels?: Record<string, string>; // every string has an English default; Arabic via labels
463
+ }
464
+
465
+ /* ------------------------------------------------------ Publishing rules */
466
+
467
+ /** What blocks Publish (E.9, E.37) — the editor lists these in a dialog. */
468
+ export type PublishBlocker =
469
+ | { kind: 'open-suggestions'; count: number }
470
+ | { kind: 'missing-plugin'; plugin: PluginId } // E.19
471
+ | { kind: 'block-without-print-view'; blockId: BlockId } // E.18
472
+ | { kind: 'unknown-field'; path: string }
473
+ /** E.44: the document names a theme the workspace doesn't have. */
474
+ | { kind: 'theme-unavailable'; ref: string }
475
+ /** #1435: printing it would exceed the render size ceiling (documents.flow_max_bytes), in bytes. */
476
+ | { kind: 'too-large'; bytes: number; max: number };