@widgetic/creator 0.3.81 → 0.4.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 (62) hide show
  1. package/README.md +157 -0
  2. package/dist/CreatorApp.svelte +1103 -612
  3. package/dist/CreatorApp.svelte.d.ts +22 -0
  4. package/dist/components/BrandKitPanel.svelte +48 -40
  5. package/dist/components/BrandKitPanel.svelte.d.ts +1 -1
  6. package/dist/components/DesignQuickEdit.svelte +13 -4
  7. package/dist/components/EditableName.svelte +13 -8
  8. package/dist/components/EditableName.svelte.d.ts +2 -2
  9. package/dist/components/FileUrlSourceControl.svelte +21 -8
  10. package/dist/components/HoverTooltip.svelte +1 -1
  11. package/dist/components/SelectorDropdown.svelte +19 -15
  12. package/dist/components/SelectorDropdown.svelte.d.ts +2 -2
  13. package/dist/components/VersionDropdownRow.svelte +14 -11
  14. package/dist/components/WidgetDetails.svelte +118 -92
  15. package/dist/components/WidgetShapeLivePreviews.svelte +105 -46
  16. package/dist/creator-types.d.ts +96 -0
  17. package/dist/host/creatorHost.d.ts +176 -0
  18. package/dist/host/creatorHost.js +242 -0
  19. package/dist/host/limitRefusal.d.ts +64 -0
  20. package/dist/host/limitRefusal.js +109 -0
  21. package/dist/i18n/index.d.ts +5 -0
  22. package/dist/i18n/index.js +5 -0
  23. package/dist/i18n/labels.d.ts +14 -0
  24. package/dist/i18n/labels.js +39 -0
  25. package/dist/i18n/language.d.ts +559 -0
  26. package/dist/i18n/language.js +47 -0
  27. package/dist/i18n/languageKit.d.ts +52 -0
  28. package/dist/i18n/languageKit.js +45 -0
  29. package/dist/i18n/messages.d.ts +526 -0
  30. package/dist/i18n/messages.js +548 -0
  31. package/dist/i18n/slots.d.ts +22 -0
  32. package/dist/i18n/slots.js +42 -0
  33. package/dist/i18n/statusText.d.ts +22 -0
  34. package/dist/i18n/statusText.js +223 -0
  35. package/dist/index.d.ts +1 -0
  36. package/dist/index.js +2 -0
  37. package/dist/stores/userSession.d.ts +8 -1
  38. package/dist/stores/userSession.js +18 -25
  39. package/dist/stores/websocketStore.d.ts +6 -0
  40. package/dist/stores/websocketStore.js +39 -4
  41. package/dist/utils/designIntentTelemetry.d.ts +8 -0
  42. package/dist/utils/designIntentTelemetry.js +52 -34
  43. package/dist/utils/directionPlacement.d.ts +51 -0
  44. package/dist/utils/directionPlacement.js +55 -0
  45. package/dist/utils/embedCode.d.ts +0 -1
  46. package/dist/utils/embedCode.js +0 -4
  47. package/dist/utils/nativeScrollbarPadding.js +1 -1
  48. package/dist/utils/pickedFile.d.ts +15 -0
  49. package/dist/utils/pickedFile.js +21 -0
  50. package/dist/utils/widgeticChatUpload.d.ts +9 -0
  51. package/dist/utils/widgeticChatUpload.js +24 -2
  52. package/package.json +5 -3
  53. package/dist/retiredSurface.test.d.ts +0 -1
  54. package/dist/retiredSurface.test.js +0 -113
  55. package/dist/utils/designIntentResolver.test.d.ts +0 -1
  56. package/dist/utils/designIntentResolver.test.js +0 -246
  57. package/dist/utils/designIntentTelemetry.test.d.ts +0 -1
  58. package/dist/utils/designIntentTelemetry.test.js +0 -385
  59. package/dist/utils/designQuickEditValues.test.d.ts +0 -1
  60. package/dist/utils/designQuickEditValues.test.js +0 -100
  61. package/dist/utils/widgeticChatUpload.test.d.ts +0 -1
  62. package/dist/utils/widgeticChatUpload.test.js +0 -257
package/README.md CHANGED
@@ -83,3 +83,160 @@ npm run clean-npm-cache # npm cache clean --force
83
83
 
84
84
  `npm run find-sveltekit-running` shows what holds port 5173;
85
85
  `npm run stop-dev` frees 5174.
86
+
87
+ ## Languages
88
+
89
+ The creator shows English until it is told otherwise. Two props of `CreatorApp` change that, and both can change while
90
+ the creator is open:
91
+
92
+ ```svelte
93
+ <CreatorApp
94
+ locale="de"
95
+ messages={{
96
+ 'creator.common.publish': 'Veröffentlichen',
97
+ 'creator.status.ready': 'Bereit',
98
+ 'creator.preview.newerThanLive': 'Neuer als Live v{version}',
99
+ 'chat.input.placeholder': 'Nachricht eingeben …',
100
+ 'canvas.tool.draw': 'Zeichnen',
101
+ }}
102
+ />
103
+ ```
104
+
105
+ - **`locale`** is a BCP 47 language tag (`de`, `pt-BR`, `ar-EG`). It decides the plural rules and how numbers, dates and
106
+ lists are written, all through `Intl`. It translates nothing. Blank or left out is English. A tag the browser does not
107
+ know is said once in the console and numbers stay English.
108
+ - **`messages`** replaces words, as ONE flat object for everything on the screen. The creator hands each part the keys
109
+ that are its own: its own words, the chat's, the canvas's, and the editor's (with the File Browser and the rich text
110
+ editor inside it). Give the keys you want to change; every key you leave out stays English, so a language can be added
111
+ one screen at a time. A key that does not exist is ignored and the console says which key you probably meant.
112
+
113
+ `ALL_CREATOR_MESSAGES` is the list to hand to a translator: an object of every key and its English text, the creator's
114
+ own (`CREATOR_MESSAGES`) and those of the parts inside it.
115
+
116
+ ```ts
117
+ import { ALL_CREATOR_MESSAGES, CREATOR_MESSAGES } from '@widgetic/creator';
118
+
119
+ console.log(Object.keys(CREATOR_MESSAGES).length); // the words of the creator itself
120
+ console.log(Object.keys(ALL_CREATOR_MESSAGES).length); // those, and the words of the chat, the canvas and the editor
121
+ console.log(CREATOR_MESSAGES['creator.embed.codeTitle']); // 'Embed Code ({format})'
122
+ ```
123
+
124
+ | Keys start with | The words of |
125
+ | --- | --- |
126
+ | `creator.common.`, `creator.general.`, `creator.session.` | words used in many places, toasts that belong to no one screen, and the lines for a visitor whose session has ended |
127
+ | `creator.widget.`, `creator.canvas.`, `creator.composition.` | creating, renaming, deleting and duplicating widgets, the canvas (loading, saving, the empty-canvas banner) and compositions with the Edit step |
128
+ | `creator.codegen.`, `creator.preview.`, `creator.version.`, `creator.versions.` | code generation, repositories and the confirm dialog, the preview banners, versions and checkpoints, and the rows of the version list |
129
+ | `creator.publish.`, `creator.embed.`, `creator.dialog.` | publishing (buttons, the reasons a publish is not possible, toasts), the Embed step and the sentences of the dialogs that have a name inside them |
130
+ | `creator.status.`, `creator.error.` | the status bar of a generation and the error texts the creator writes itself (see "What stays as it is") |
131
+ | `creator.details.`, `creator.brandKit.`, `creator.livePreviews.` | the widget details panel, the brand kit panel and the live previews drawn on the canvas shapes |
132
+ | `creator.selector.`, `creator.name.`, `creator.designEdit.`, `creator.fileSource.` | the dropdown that picks a canvas or a composition, the editable name, the quick edit of design values and the control that takes a file or a web address |
133
+ | `chat.`, `canvas.`, `editor.`, `shadEditor.` and the File Browser's own keys | the chat, the canvas, the editor, the rich text editor of its text boxes and the File Browser that picks a file |
134
+
135
+ ### Writing a message
136
+
137
+ A message is text. Two kinds of `{...}` have a meaning:
138
+
139
+ | Write | It shows |
140
+ | --- | --- |
141
+ | `{name}` | a value the creator puts in (`'creator.dialog.deleteCanvas': 'Are you sure you want to delete {name}? …'`). A number is written the way the locale writes numbers. |
142
+ | `{count, plural, one {# widget} other {# widgets}}` | the branch that fits the number in the page's language. `other` is required; `=0 {none}` matches exactly 0; `#` is the number. |
143
+
144
+ `\{`, `\}`, `\#` and `\\` write that character itself. Each English message names the values it is given: a translation
145
+ may leave one out, and may use a value in any order, but it cannot ask for a value the message is never given (it would
146
+ show as written, `{other}`). A sentence with a name in the middle of it, in bold (the dialogs that ask whether to delete
147
+ a canvas or a widget), is cut where the name goes: put the name where your language needs it.
148
+
149
+ ### Finding a mistake before a visitor does
150
+
151
+ `checkCreatorMessages(messages)` checks a `messages` object without showing anything, and `describeMessageProblem` (from
152
+ `@widgetic/design-system/i18n`) turns each problem into a sentence. It finds a key that does not exist (with the nearest
153
+ real one), a value that is not text, a template that does not parse, and a message that asks for a value it is never
154
+ given, across all the catalogs above. An empty list means every message will be used. Put it in a test of your page:
155
+
156
+ ```ts
157
+ import { checkCreatorMessages } from '@widgetic/creator';
158
+ import { describeMessageProblem } from '@widgetic/design-system/i18n';
159
+ import german from './creator.de.json';
160
+
161
+ expect(checkCreatorMessages(german).map(describeMessageProblem)).toEqual([]);
162
+ ```
163
+
164
+ While the creator runs, a message that cannot be used is never thrown: the English text of that key is shown and the
165
+ console says `[Creator] ...` once.
166
+
167
+ ### What stays as it is
168
+
169
+ - **Words that belong to someone else.** The names of widgets, canvases and compositions, what people typed into the
170
+ chat, and what the assistant writes back are shown as they were written.
171
+ - **The status bar and the error boxes.** The creator stores its status lines and failures in English, because the
172
+ chat and a saved conversation read them back. They are shown in the page's language when the line is one the creator
173
+ knows (`src/lib/i18n/statusText.ts` is the table, and a test fails when a line is written that the table does not
174
+ have). The reason of a failure ("Code generation failed: …") is said the same way. A line that came from the server,
175
+ or one with a commit hash in it (debug mode), is shown as it came.
176
+ - **What is written into a conversation or saved with a widget.** The lines the creator adds to the chat and the default
177
+ names it saves (a conversation's title, an untitled widget) stay in the language they were written in.
178
+ - **Parts a partner's creator never draws.** A creator given `getAccessToken` is always embedded, and debug mode is
179
+ something the host has to ask for (the widget creator module never does), so the sign-in page, the header of the
180
+ standalone creator, the debug panels (console, model pickers, the list of widgets) and the administrator's delete are
181
+ not translated. The password field of the design system, used only there, has English alt text.
182
+ - **Technical text.** Errors that are thrown, console output, the server's error messages and the prompts sent to the
183
+ AI stay as they are.
184
+
185
+ ### Right to left
186
+
187
+ Arabic, Hebrew, Persian and Urdu start a line on the right. `CreatorApp` takes one more prop for that, and it can change
188
+ while the creator is open:
189
+
190
+ ```svelte
191
+ <CreatorApp locale="ar" messages={arabic} dir="rtl" />
192
+ ```
193
+
194
+ - **`dir`** is `'rtl'` or `'ltr'`. It is not taken from `locale`: it says which way the screen is read, and a page decides
195
+ that (`resolveTextDirection(locale)` from `@widgetic/design-system/i18n` answers it for a language tag; the
196
+ `@widgetic/ui-sdk` module does exactly this). Left out, the creator follows the direction of the screen it sits in (a
197
+ component above it that calls `provideTextDirection(store)` from `@widgetic/design-system/components/textDirection`),
198
+ and with neither it is left to right, as it always was. The creator writes `dir` on its own root and hands it to the
199
+ chat, the canvas and the editor inside it, which follow it.
200
+ - **What turns around.** The tools of the toolbar run from the start of the line and the properties panel is docked at
201
+ the end of it; the context menu, the list of shapes, the publish history, the starting-point picker and the panels of
202
+ the editor are laid out from the start. Things that are put in place in pixels are mirrored where they are placed
203
+ (`src/lib/utils/directionPlacement.ts`): a divider is dragged toward the end of the line (`distanceTowardEnd`), a list
204
+ under a cluster of controls is lined up with the end edge of the cluster (`listAlignedToEnd`), the title of a widget in
205
+ its panel is given the room up to the box that stands beyond it (`roomBeforeNeighbour`; measured the left to right way it
206
+ came out negative and the title showed as a dot), and the pop-up of the brand kit hangs from the start edge of its
207
+ button (`popUpLeftFromAnchor`).
208
+ - **What a person types** (the chat box, the text fields of the quick edit) is read by its own first letter on a right to
209
+ left screen, and a field with nothing in it yet takes the direction of the screen. A link (the file link field) and a
210
+ colour code are addresses and stay left to right on every screen.
211
+ - **Left to right on every screen.** The drawing board (the canvas package draws it as `<canvas dir="ltr">`) and the live
212
+ previews of widgets (`WidgetShapeLivePreviews.svelte`) are drawings, not lines of text, and say `dir="ltr"` themselves.
213
+ Code is code: the one block of it the creator draws, the embed code of the *Embed* step, is not part of an embedded
214
+ creator and is not turned around.
215
+ - **One thing that is not mirrored.** The panel of a widget opens on the side of its shape that has more room
216
+ (`opensOnRightOfShape`). That is a question about the picture, not about the line, so it is the same in both directions
217
+ except for a shape exactly in the middle, and it does not know where the properties panel is: for a shape near the middle
218
+ of the board it can open over it (in English, over the panel at the other side).
219
+ - **Keeping it so.** `src/lib/direction.test.ts` reads the source of the creator with `auditPhysicalPlacement` from
220
+ `@widgetic/design-system/rtl/audit`, fails on a class or a style that puts something on a physical side (`left`, `right`,
221
+ `ml-`, `pr-`, `text-left`, four-value shorthands such as `inset: 0 2.5rem 0 0` ...: write `start`/`end`, or say why with
222
+ the note `rtl-ok` on the same line or the line above), and pins the helpers above and every `dir="ltr"` that is on
223
+ purpose. Look at the creator in a right to left browser as well (`?locale=ar` in the harness of `@widgetic/ui-sdk`): some
224
+ mistakes are not in the source.
225
+
226
+ ### Tests
227
+
228
+ The words have tests of their own in `src/lib/i18n/` (`npm run test:unit`). They read the source of the creator and fail
229
+ on a sentence written into a part a partner's creator draws (the few that must stay in the code are listed with a reason
230
+ in `source.test.ts`), a key the code asks for that the catalog does not have or the other way round, a message that asks
231
+ for a value it is never given, a line written into a status that the table does not know, and a design-system
232
+ component that shows words of its own but is not given all of them. Two limits: the build drops `console.*` calls, so the
233
+ tests cannot hear a console warning, and `language.ts` imports the chat's Svelte source, which vitest cannot compile, so
234
+ they test the same code through `createCreatorLanguageKit`. The browser tests of the widget creator module in `ui-sdk`
235
+ cover the glue.
236
+
237
+ ### In development
238
+
239
+ The dev server and the tests resolve `@widgetic/design-system/i18n` and `@widgetic/design-system/rtl` through
240
+ `@widgetic/dev-tools`. An installed dev-tools that does not list those paths yet breaks both; `vite.config.ts` adds the
241
+ aliases itself in that case, and the
242
+ alias goes away by itself once dev-tools has it.