@widgetic/workflows 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 (149) hide show
  1. package/LICENSE +122 -0
  2. package/README.md +304 -2
  3. package/dist/api/apiContext.d.ts +4 -0
  4. package/dist/api/apiContext.js +17 -0
  5. package/dist/api/types.d.ts +168 -0
  6. package/dist/api/types.js +3 -0
  7. package/dist/api/workflowsApi.d.ts +109 -0
  8. package/dist/api/workflowsApi.js +657 -0
  9. package/dist/components/Workflows.svelte +131 -0
  10. package/dist/components/Workflows.svelte.d.ts +4 -0
  11. package/dist/components/WorkflowsEmptyState.svelte +32 -0
  12. package/dist/components/WorkflowsEmptyState.svelte.d.ts +7 -0
  13. package/dist/components/WorkflowsHeader.svelte +14 -0
  14. package/dist/components/WorkflowsHeader.svelte.d.ts +18 -0
  15. package/dist/components/WorkflowsWorkspace.svelte +87 -0
  16. package/dist/components/WorkflowsWorkspace.svelte.d.ts +14 -0
  17. package/dist/components/canvas/AddBlockMenu.svelte +101 -0
  18. package/dist/components/canvas/AddBlockMenu.svelte.d.ts +5 -0
  19. package/dist/components/canvas/CanvasToolbar.svelte +95 -0
  20. package/dist/components/canvas/CanvasToolbar.svelte.d.ts +9 -0
  21. package/dist/components/canvas/CompositionNodeView.svelte +125 -0
  22. package/dist/components/canvas/CompositionNodeView.svelte.d.ts +5 -0
  23. package/dist/components/canvas/ConditionNodeView.svelte +95 -0
  24. package/dist/components/canvas/ConditionNodeView.svelte.d.ts +5 -0
  25. package/dist/components/canvas/HandlePoint.svelte +32 -0
  26. package/dist/components/canvas/HandlePoint.svelte.d.ts +14 -0
  27. package/dist/components/canvas/TriggerNodeView.svelte +75 -0
  28. package/dist/components/canvas/TriggerNodeView.svelte.d.ts +5 -0
  29. package/dist/components/canvas/WorkflowCanvas.svelte +380 -0
  30. package/dist/components/canvas/WorkflowCanvas.svelte.d.ts +25 -0
  31. package/dist/components/canvas/WorkflowEdgeView.svelte +58 -0
  32. package/dist/components/canvas/WorkflowEdgeView.svelte.d.ts +4 -0
  33. package/dist/components/editor/EditorBanners.svelte +143 -0
  34. package/dist/components/editor/EditorBanners.svelte.d.ts +7 -0
  35. package/dist/components/editor/EditorCanvasArea.svelte +85 -0
  36. package/dist/components/editor/EditorCanvasArea.svelte.d.ts +3 -0
  37. package/dist/components/editor/EditorTabs.svelte +81 -0
  38. package/dist/components/editor/EditorTabs.svelte.d.ts +7 -0
  39. package/dist/components/editor/EditorTopBar.svelte +132 -0
  40. package/dist/components/editor/EditorTopBar.svelte.d.ts +9 -0
  41. package/dist/components/editor/RunsTab.svelte +256 -0
  42. package/dist/components/editor/RunsTab.svelte.d.ts +3 -0
  43. package/dist/components/editor/SettingsTab.svelte +180 -0
  44. package/dist/components/editor/SettingsTab.svelte.d.ts +7 -0
  45. package/dist/components/editor/WorkflowEditor.svelte +185 -0
  46. package/dist/components/editor/WorkflowEditor.svelte.d.ts +15 -0
  47. package/dist/components/index.d.ts +1 -0
  48. package/dist/components/index.js +1 -0
  49. package/dist/components/list/CreateWorkflowDialog.svelte +89 -0
  50. package/dist/components/list/CreateWorkflowDialog.svelte.d.ts +9 -0
  51. package/dist/components/list/WorkflowList.svelte +204 -0
  52. package/dist/components/list/WorkflowList.svelte.d.ts +12 -0
  53. package/dist/components/list/WorkflowRow.svelte +191 -0
  54. package/dist/components/list/WorkflowRow.svelte.d.ts +10 -0
  55. package/dist/components/panel/BlockProblems.svelte +47 -0
  56. package/dist/components/panel/BlockProblems.svelte.d.ts +6 -0
  57. package/dist/components/panel/CompositionForm.svelte +127 -0
  58. package/dist/components/panel/CompositionForm.svelte.d.ts +7 -0
  59. package/dist/components/panel/CompositionPicker.svelte +179 -0
  60. package/dist/components/panel/CompositionPicker.svelte.d.ts +14 -0
  61. package/dist/components/panel/ConditionForm.svelte +105 -0
  62. package/dist/components/panel/ConditionForm.svelte.d.ts +7 -0
  63. package/dist/components/panel/EventValueRow.svelte +85 -0
  64. package/dist/components/panel/EventValueRow.svelte.d.ts +12 -0
  65. package/dist/components/panel/NextStepSelect.svelte +70 -0
  66. package/dist/components/panel/NextStepSelect.svelte.d.ts +12 -0
  67. package/dist/components/panel/ProblemsList.svelte +101 -0
  68. package/dist/components/panel/ProblemsList.svelte.d.ts +3 -0
  69. package/dist/components/panel/RuleCard.svelte +191 -0
  70. package/dist/components/panel/RuleCard.svelte.d.ts +13 -0
  71. package/dist/components/panel/SidePanel.svelte +82 -0
  72. package/dist/components/panel/SidePanel.svelte.d.ts +3 -0
  73. package/dist/components/panel/TestRow.svelte +150 -0
  74. package/dist/components/panel/TestRow.svelte.d.ts +15 -0
  75. package/dist/components/panel/TestRunPanel.svelte +85 -0
  76. package/dist/components/panel/TestRunPanel.svelte.d.ts +3 -0
  77. package/dist/components/panel/TestTriggerCard.svelte +121 -0
  78. package/dist/components/panel/TestTriggerCard.svelte.d.ts +7 -0
  79. package/dist/components/panel/TriggerForm.svelte +385 -0
  80. package/dist/components/panel/TriggerForm.svelte.d.ts +7 -0
  81. package/dist/components/panel/VersionHistory.svelte +123 -0
  82. package/dist/components/panel/VersionHistory.svelte.d.ts +3 -0
  83. package/dist/components/ui/ActionButton.svelte +85 -0
  84. package/dist/components/ui/ActionButton.svelte.d.ts +27 -0
  85. package/dist/components/ui/ConfirmDialog.svelte +52 -0
  86. package/dist/components/ui/ConfirmDialog.svelte.d.ts +16 -0
  87. package/dist/components/ui/Icon.svelte +32 -0
  88. package/dist/components/ui/Icon.svelte.d.ts +9 -0
  89. package/dist/components/ui/Menu.svelte +211 -0
  90. package/dist/components/ui/Menu.svelte.d.ts +21 -0
  91. package/dist/components/ui/Modal.svelte +129 -0
  92. package/dist/components/ui/Modal.svelte.d.ts +13 -0
  93. package/dist/components/ui/Notice.svelte +36 -0
  94. package/dist/components/ui/Notice.svelte.d.ts +11 -0
  95. package/dist/components/ui/SelectField.svelte +74 -0
  96. package/dist/components/ui/SelectField.svelte.d.ts +16 -0
  97. package/dist/components/ui/StatusBadge.svelte +41 -0
  98. package/dist/components/ui/StatusBadge.svelte.d.ts +9 -0
  99. package/dist/components/ui/TextField.svelte +97 -0
  100. package/dist/components/ui/TextField.svelte.d.ts +29 -0
  101. package/dist/components/ui/icons.d.ts +34 -0
  102. package/dist/components/ui/icons.js +54 -0
  103. package/dist/components/ui/types.d.ts +26 -0
  104. package/dist/components/ui/types.js +1 -0
  105. package/dist/editor/apiErrorText.d.ts +10 -0
  106. package/dist/editor/apiErrorText.js +53 -0
  107. package/dist/editor/autosave.d.ts +47 -0
  108. package/dist/editor/autosave.js +119 -0
  109. package/dist/editor/blockLabels.d.ts +91 -0
  110. package/dist/editor/blockLabels.js +196 -0
  111. package/dist/editor/canvasContext.d.ts +52 -0
  112. package/dist/editor/canvasContext.js +37 -0
  113. package/dist/editor/canvasWords.d.ts +24 -0
  114. package/dist/editor/canvasWords.js +40 -0
  115. package/dist/editor/capabilityModel.d.ts +46 -0
  116. package/dist/editor/capabilityModel.js +113 -0
  117. package/dist/editor/editorState.svelte.d.ts +220 -0
  118. package/dist/editor/editorState.svelte.js +713 -0
  119. package/dist/editor/flowAdapter.d.ts +59 -0
  120. package/dist/editor/flowAdapter.js +166 -0
  121. package/dist/editor/formatCount.d.ts +5 -0
  122. package/dist/editor/formatCount.js +15 -0
  123. package/dist/editor/graphDiff.d.ts +27 -0
  124. package/dist/editor/graphDiff.js +64 -0
  125. package/dist/editor/graphModel.d.ts +154 -0
  126. package/dist/editor/graphModel.js +457 -0
  127. package/dist/editor/issueText.d.ts +64 -0
  128. package/dist/editor/issueText.js +101 -0
  129. package/dist/editor/listState.svelte.d.ts +82 -0
  130. package/dist/editor/listState.svelte.js +250 -0
  131. package/dist/editor/statsRange.d.ts +26 -0
  132. package/dist/editor/statsRange.js +41 -0
  133. package/dist/editor/testRun.d.ts +36 -0
  134. package/dist/editor/testRun.js +74 -0
  135. package/dist/editor/zonedTime.d.ts +20 -0
  136. package/dist/editor/zonedTime.js +134 -0
  137. package/dist/i18n/index.d.ts +2 -0
  138. package/dist/i18n/index.js +2 -0
  139. package/dist/i18n/language.d.ts +22 -0
  140. package/dist/i18n/language.js +34 -0
  141. package/dist/i18n/messages.d.ts +423 -0
  142. package/dist/i18n/messages.js +446 -0
  143. package/dist/index.d.ts +4 -0
  144. package/dist/index.js +5 -0
  145. package/dist/types/index.d.ts +66 -0
  146. package/dist/types/index.js +1 -0
  147. package/dist/utils/logger.d.ts +4 -0
  148. package/dist/utils/logger.js +35 -0
  149. package/package.json +103 -5
package/LICENSE ADDED
@@ -0,0 +1,122 @@
1
+ Widgetic Integration License
2
+ Version 1.0
3
+
4
+ Copyright (c) Widgetic. All rights reserved.
5
+
6
+ This license covers the software package that it came with, in source and
7
+ compiled form, together with its documentation (the "Software"). By
8
+ installing, copying or using the Software you accept this license. If you do
9
+ not accept it, do not install or use the Software.
10
+
11
+ In this license, "Widgetic" is the company that publishes the Software, "you"
12
+ is the person or organization that uses it, and "Your Application" is an
13
+ application, website, product or service that you build or operate, for
14
+ yourself or for a client. "Widgetic Services" are the services that Widgetic
15
+ operates: the Widgetic API, widgets, compositions, embeds, editors, file
16
+ browser, chat and AI creator, and the other services that can be reached from
17
+ widgetic.com or its API hosts.
18
+
19
+ 1. What you may do
20
+
21
+ Widgetic grants you a worldwide, non-exclusive, non-transferable and
22
+ non-sublicensable license to use the Software, unmodified, for one purpose: to
23
+ integrate the Widgetic Services into Your Application. Within that purpose you
24
+ may:
25
+
26
+ (a) install the Software and run it in Your Application, in development,
27
+ testing and production;
28
+
29
+ (b) use it to call the Widgetic API, to show Widgetic widgets and
30
+ compositions, and to open Widgetic's editors, file browser, chat and AI
31
+ creator inside Your Application;
32
+
33
+ (c) bundle, minify and tree-shake the Software with the build tools of Your
34
+ Application, deliver the result to the people who use Your Application as a
35
+ part of it, and let them run it there;
36
+
37
+ (d) keep the copies of the Software that (a), (b) and (c) need, including
38
+ copies in your version control, your build systems and your backups.
39
+
40
+ 2. What you may not do
41
+
42
+ You may not, and may not allow anyone else to:
43
+
44
+ (a) use the Software for any purpose other than the one in section 1;
45
+
46
+ (b) use the Software to build, run or improve a service that offers what the
47
+ Widgetic Services offer, or to connect Your Application to anything other than
48
+ the Widgetic Services (a proxy of yours that forwards calls to the Widgetic
49
+ Services is fine);
50
+
51
+ (c) copy, modify, translate, adapt or make derivative works of the Software,
52
+ except as section 1(c) allows;
53
+
54
+ (d) publish, sell, rent, lease, sublicense or distribute the Software on its
55
+ own, or inside a library, SDK, template or product that others could use for
56
+ anything other than integrating the Widgetic Services, including by
57
+ publishing it, or a copy of it, to a package registry or a public CDN;
58
+
59
+ (e) reverse engineer, decompile or disassemble the Software, or try to get at
60
+ its source code, except as far as the law lets you despite this restriction;
61
+
62
+ (f) remove or change a copyright, license or attribution notice in the
63
+ Software;
64
+
65
+ (g) bypass, disable or interfere with the authentication, rate limits, quotas,
66
+ credits, plan limits or other protections of the Widgetic Services, or help
67
+ anyone else to;
68
+
69
+ (h) use the name, logo or trademarks of Widgetic, except to say truthfully
70
+ that Your Application integrates Widgetic.
71
+
72
+ 3. The Widgetic Services are separate
73
+
74
+ This license is for the Software only. It does not give you the right to use
75
+ the Widgetic Services. That right comes from your account or agreement with
76
+ Widgetic and from Widgetic's Terms of Service (https://widgetic.com/terms),
77
+ which this license does not change.
78
+
79
+ 4. Ownership
80
+
81
+ The Software is licensed to you, not sold. Widgetic and its licensors keep all
82
+ rights in it. Any right that this license does not give you in plain words is
83
+ reserved to Widgetic.
84
+
85
+ 5. Third-party software
86
+
87
+ The Software may include or depend on software from others. That software is
88
+ under its own license, which applies to it instead of this one, and nothing in
89
+ this license limits your rights under it.
90
+
91
+ 6. How long it lasts
92
+
93
+ This license lasts while you follow it and while you are entitled to use the
94
+ Widgetic Services. It ends on its own if you break it or that entitlement
95
+ ends. When it ends, you stop using the Software and delete your copies of it,
96
+ except copies that the law requires you to keep. Sections 4, 8 and 9 still
97
+ apply after it has ended.
98
+
99
+ 7. Versions
100
+
101
+ This license applies to the version of the Software that it came with and to
102
+ later versions that carry it. A version that Widgetic published under another
103
+ license stays under that license, for the copies of it that you already have.
104
+
105
+ 8. No warranty
106
+
107
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
108
+ IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
109
+ PURPOSE AND NON-INFRINGEMENT.
110
+
111
+ 9. Limit of liability
112
+
113
+ TO THE EXTENT THE LAW ALLOWS, WIDGETIC IS NOT LIABLE FOR ANY INDIRECT,
114
+ INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR LOST PROFITS,
115
+ REVENUE, DATA OR GOODWILL, THAT ARISE FROM THE SOFTWARE OR FROM THIS LICENSE,
116
+ EVEN IF IT HAS BEEN TOLD THAT THEY ARE POSSIBLE. NOTHING IN THIS LICENSE
117
+ LIMITS A LIABILITY THAT THE LAW DOES NOT ALLOW TO BE LIMITED.
118
+
119
+ 10. Questions
120
+
121
+ If you need to do something that this license does not allow, ask first:
122
+ support@widgetic.com.
package/README.md CHANGED
@@ -1,3 +1,305 @@
1
- # Temporary Holding Version
1
+ # @widgetic/workflows
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Workflows for Widgetic: chain compositions together, with filters between them that decide which composition an embed
4
+ shows. One Svelte package that the Widgetic site, partners and Shopify all load.
5
+
6
+ > **Status: the list and the node editor are built** (0.2.0). A workspace's workflows are listed, searched and ordered; a
7
+ > workflow is drawn on a canvas of blocks with a side panel, versions, a test run and the counts of where visitors went.
8
+ > What a workflow is, what was decided and why, and the line between a workflow and the Embed SDK are in
9
+ > [`__docs/concepts.md`](./__docs/concepts.md).
10
+
11
+ Workflows are for **Teams and partner accounts** only. On Widgetic the page is
12
+ `/workspaces/<workspace>/experiments/workflows`, below _Translations_ in the sidebar.
13
+
14
+ ## What it does
15
+
16
+ - **The list.** The workspace's workflows with where each one stands (draft, live, paused, archived), how many visitors
17
+ went through, and when it was last published. Search by name, show or hide the archived ones, order by name, date
18
+ created, last published or visitors, and make a workflow (`New workflow`), duplicate it or delete it. The page is told
19
+ when one is opened (`onOpenWorkflow`) so the address can follow.
20
+ - **The editor.** A canvas of blocks joined by lines. A **Composition** block shows a composition; a **Trigger** block
21
+ waits for something a visitor does (a value they add to a widget, an action in the widget, an event on the page, or a
22
+ time); a **Condition** block sends the visitor on by the first rule that matches. Blocks go forward only, a workflow
23
+ holds up to 25 of them, and exactly one composition starts it. The side panel edits the selected block; a published
24
+ version never changes, and visitors who are in the middle of a workflow finish on the version they started on.
25
+ - **Only what a widget can do is offered.** A trigger is enabled for a composition only when its widget can supply it:
26
+ values a visitor adds need a Pro widget that keeps data, actions need a widget that reports them. The reason is told
27
+ next to the choice, and the check at publish is the API's, not the screen's.
28
+ - **Draft, publish, versions.** Changes are saved as a draft while you work (and when the page is put away). _Publish_
29
+ makes a version, _Discard changes_ goes back to the live one, and the version history shows any earlier version
30
+ read-only. A banner says when the draft differs from what is live.
31
+ - **Test run.** A visitor is played through the draft on the canvas: fire a trigger and watch the path light up. Nothing is
32
+ stored and no real visitor is touched.
33
+ - **Runs.** The _Runs_ tab shows how many visitors went through each block and each line over a range of days (counts
34
+ only: what a visitor typed is never stored).
35
+ - **Settings.** The time zone that scheduled triggers are told in, the embed code, and the state of the workflow: pause
36
+ or resume it, archive or restore it, duplicate it, or delete it (only a draft that was never published: a published
37
+ workflow can only be archived, because pages may still use it). The name is edited in the bar above the canvas.
38
+ - Speaks the page's language (`locale`, `messages`) and turns around for right to left (`dir`).
39
+ - Takes its colours, font and corners from CSS custom properties, so a host or a ui-sdk theme restyles it.
40
+ - Reports what goes wrong to the page (`onError`) and shows the visitor a "Try again" in place of a part that failed.
41
+
42
+ ## Where it is loaded
43
+
44
+ | Host | How |
45
+ | ------------- | ------------------------------------------------------------------------------------------------- |
46
+ | Widgetic site | `import { Workflows } from '@widgetic/workflows'` on the page, as it does for chat and editor |
47
+ | Partners | The `workflows` module of `@widgetic/ui-sdk`, loaded from the CDN with `ui.mount('workflows', …)` |
48
+ | Shopify | The same ui-sdk module, through a host component (later) |
49
+
50
+ How the three fit together, and the order they are released in: [`__docs/package-chain.md`](./__docs/package-chain.md).
51
+
52
+ ## Install
53
+
54
+ ```bash
55
+ npm install @widgetic/workflows @widgetic/design-system svelte
56
+ ```
57
+
58
+ `@widgetic/design-system` and `svelte` are peer dependencies. The host brings them, so there is one copy of each on the
59
+ page. The package needs Svelte 5.
60
+
61
+ **Styles.** The components are styled with Tailwind classes and ship no stylesheet of their own, so the host's Tailwind
62
+ has to read the package, or the screen is drawn without its classes. In the host's CSS, after the design system:
63
+
64
+ ```css
65
+ @import '@widgetic/design-system/styles';
66
+ @source '../node_modules/@widgetic/workflows/dist'; /* the path is relative to this CSS file */
67
+ ```
68
+
69
+ ## Use
70
+
71
+ ```svelte
72
+ <script lang="ts">
73
+ import { Workflows } from '@widgetic/workflows';
74
+ import { resolveTextDirection } from '@widgetic/design-system/i18n';
75
+
76
+ const locale = 'ar';
77
+ const arabicMessages = { 'workflows.header.title': 'سير العمل' };
78
+
79
+ /** A token the API accepts for the person; called with 'initial', and with 'expired' after a refusal. */
80
+ async function getAccessToken({ reason }) {
81
+ return (await fetch('/my-server/widgetic-token?reason=' + reason)).text();
82
+ }
83
+ </script>
84
+
85
+ <Workflows
86
+ apiUrl="https://api.widgetic.com"
87
+ {getAccessToken}
88
+ workspaceId="personal"
89
+ {locale}
90
+ messages={arabicMessages}
91
+ dir={resolveTextDirection(locale)}
92
+ onOpenWorkflow={(workflowId) =>
93
+ history.pushState(null, '', workflowId ? `/workflows/${workflowId}` : '/workflows')}
94
+ onError={(error) => console.warn(error.code, error.message)}
95
+ />
96
+ ```
97
+
98
+ The screen fills the height and width of the element it sits in. Give that element a size. When the element is shorter than
99
+ the screen needs, the screen scrolls inside it; it never spills over what the page has below.
100
+
101
+ ### Props
102
+
103
+ | Prop | Type | Default | What it does |
104
+ | --------------------- | ------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
105
+ | `apiUrl` | `string` | **required** | The Widgetic API origin, without `/v1` (`https://api.widgetic.com`). |
106
+ | `getAccessToken` | `AccessTokenFunction` | **required** | Gives the screen a token for the API. Called with `'initial'` and, after a refusal, `'expired'`. The screen never stores a token. |
107
+ | `workspaceId` | `string` | **required** | `personal`, or the id of the organization whose workflows are shown. A change of it starts the screen again. |
108
+ | `workflowId` | `string \| null` | the list | The workflow that is open. The page owns it (it is part of the page's address); left out, the screen keeps track by itself. |
109
+ | `onOpenWorkflow` | `(workflowId: string \| null) => void` | none | The person opened a workflow, or went back to the list (`null`). |
110
+ | `onShowEmbedCode` | `(workflowId: string) => void` | none | Shows the embed code of a workflow. The dialog is the page's (it knows how the tag is built for its Embed SDK); without it there is no button. |
111
+ | `locale` | `string \| null` | English | A BCP 47 tag (`de`, `pt-BR`): plural rules, how numbers and dates are written. Translates nothing. |
112
+ | `messages` | `Readonly<Record<string, unknown>> \| null` | none | Your own words, by key. A key you leave out stays English. |
113
+ | `dir` | `'ltr' \| 'rtl'` | the screen around it | Which way the screen is read. You decide it; it is not worked out from `locale`. |
114
+ | `class` | `string` | `''` | Extra classes on the root element. |
115
+ | `onError` | `(error: WorkflowsError) => void` | none | Called once for each failure. |
116
+ | `fetchImplementation` | `typeof fetch` | the page's `fetch` | For tests and previews: the `fetch` the screen asks the API with. |
117
+
118
+ `WorkflowsError` is `{ message: string; code: 'RENDER_FAILED' | 'REQUEST_FAILED' | 'SESSION_ENDED'; fatal: boolean }`.
119
+ The `message` is English, for the page's developer. It is not a sentence to show a visitor: the screen shows its own.
120
+
121
+ **What the screen asks of the API.** `GET/POST /v1/workspaces/{workspaceId}/workflows` and the routes under it (a
122
+ workflow, its draft, publish, discard, versions, stats, composition options), always as the person: the token is
123
+ the person's, and a call the person may not make is refused by the API. The screen holds no service key (a test fails the
124
+ build if any code of the package that runs in a browser reads one). A change is sent with an `Idempotency-Key`, and a draft
125
+ with the revision the editor was given, so a draft changed somewhere else is told, not overwritten.
126
+
127
+ ## Look and feel
128
+
129
+ Nothing in the screen is a literal colour, font or corner. It reads the Widgetic palette, and a theme is a handful of
130
+ those values set as CSS custom properties on an element that contains the screen. A colour is three numbers (hue,
131
+ saturation, lightness) with no `hsl()` around them, because the components write `hsl(var(--grey2))`.
132
+
133
+ | Property | What it paints |
134
+ | ----------------------------------------------------- | -------------------------------------------------------------------------- |
135
+ | `--ink-primary` | The titles and the text. |
136
+ | `--ink-muted` | The lines under a title, the hints and the labels. |
137
+ | `--ink-subtle` | The faintest text: placeholders and disabled words. |
138
+ | `--grey2` | Borders, dividers and the dashed border of the empty state. |
139
+ | `--primary-green` | The brand colour: the main buttons, the selected block and the live state. |
140
+ | `--error` | Problems on a block, failed saves and the title of the failure state. |
141
+ | `--radius-small`, `--radius-medium`, `--radius-large` | The corners of the fields, the buttons and the cards and panels. |
142
+ | `--font-sans` | The typeface. |
143
+
144
+ ```css
145
+ .my-workflows-host {
146
+ --primary-green: 262 83% 50%;
147
+ --ink-primary: 262 60% 14%;
148
+ --ink-muted: 262 20% 40%;
149
+ --grey2: 262 45% 80%;
150
+ --radius-large: 2px;
151
+ --font-sans: Georgia, serif;
152
+ }
153
+ ```
154
+
155
+ The surface is white (`bg-white`). Inside a ui-sdk module it follows the theme's `background`.
156
+
157
+ **For partners** the module takes a `theme` (a preset or `{ colors, radius, font }`), and the module spreads it over
158
+ these properties, so a partner never writes one by hand.
159
+
160
+ **For the people who write this package:** a colour, a font or a corner in a component is a token, never a literal.
161
+ `tests/workflows-theming.test.mjs` fails on a hex colour, a colour function, a colour of Tailwind's own palette, an
162
+ arbitrary value or a `style` attribute, and says what to write instead. Placement uses the start and the end of a line
163
+ (`ms-`, `me-`, `text-start`), never a physical side; `tests/workflows-direction.test.mjs` fails on `ml-`, `left-` and
164
+ the like unless the line says why with the note `rtl-ok`.
165
+
166
+ The shadcn names (`--background`, `--foreground`, `--muted`) are **not** what this package reads. The Widgetic site does
167
+ not define them, so a screen written against them would have no colour there.
168
+
169
+ ## Languages
170
+
171
+ Every word a person reads is a message in a catalog of English sentences, `WORKFLOWS_MESSAGES`, keyed
172
+ `workflows.<where>.<what>`. A page gives its own words with `messages`; what it leaves out stays English, so a language
173
+ can be added a screen at a time.
174
+
175
+ The catalog has 390 messages. They are grouped by the part of the screen that says them:
176
+
177
+ | Group | What it says |
178
+ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
179
+ | `workflows.header.*`, `empty.*` | The title and the empty state. |
180
+ | `workflows.list.*`, `create.*`, `status.*` | The list: search, filter, order, rows, the New workflow dialog, states. |
181
+ | `workflows.top.*`, `save.*`, `tabs.*`, `banner.*`, `leave.*` | The bar above the canvas, the save state, the tabs and the banners. |
182
+ | `workflows.canvas.*`, `toolbar.*`, `addBlock.*`, `block.*` | The canvas, its tools, the Add block menu and what a block is called. |
183
+ | `workflows.panel.*`, `composition.*`, `trigger.*`, `schedule.*`, `event.*`, `reason.*` | The side panel for a composition and for each kind of trigger, and why a trigger is not offered. |
184
+ | `workflows.condition.*`, `rule.*`, `test.*`, `operator.*`, `fieldType.*`, `value.*` | A condition, its rules, their tests and the words around them. |
185
+ | `workflows.history.*`, `runs.*`, `settings.*`, `publish.*`, `editor.*` | Versions, the Runs tab, Settings, publishing. |
186
+ | `workflows.issue.*` | What the engine finds wrong with a workflow, one message for each code it can report. |
187
+ | `workflows.error.*` | The failure state, and what a failed request means (one message for each way it can fail). |
188
+
189
+ `WORKFLOWS_MESSAGES` lists all of them with their English text, and a test fails when a message is not used or a sentence is
190
+ written into a file instead of the catalog. A test also reads the engine's own list of issue codes, so a code the engine
191
+ adds without a message here fails the build.
192
+
193
+ A message is plain text. `{name}` is a value the screen puts in, and
194
+ `{count, plural, one {# step} other {# steps}}` picks the form that fits a number in the page's language. The whole
195
+ format is described in `@widgetic/design-system/i18n`. A message is never written into the page as HTML.
196
+
197
+ Check your words before a visitor does:
198
+
199
+ ```ts
200
+ import { checkWorkflowsMessages } from '@widgetic/workflows';
201
+
202
+ // [] when every message will be used; otherwise a list that names each mistake
203
+ // (a key that does not exist, with the nearest real one; a template that does not parse)
204
+ console.log(checkWorkflowsMessages({ 'workflows.header.titel': 'Workflows' }));
205
+ ```
206
+
207
+ **The package ships English only; the other languages are packs of the module.** The twelve languages that the other
208
+ `@widgetic/ui-sdk` modules ship (`fr`, `de`, `es`, `pt-BR`, `nl`, `da`, `sv`, `zh-CN`, `ar`, `he`, `fa`, `ur`) are lazy
209
+ packs of the `workflows` module: the module loads the pack for the page's `locale` and hands it to this package as
210
+ `messages`, so a partner chooses a language with `locale` alone. A host that loads this package directly, as the
211
+ Widgetic site does, passes `messages` itself.
212
+
213
+ **Right to left.** Pass `dir="rtl"` (`resolveTextDirection(locale)` answers it for a language tag). The screen mirrors by
214
+ itself: everything is placed by the start and end of a line.
215
+
216
+ ## Errors
217
+
218
+ A part of the screen that throws while it is drawn is caught by a `<svelte:boundary>`. The screen shows "Workflows could
219
+ not be shown" with a **Try again** button in its place, and the page's `onError` is called once with
220
+ `{ code: 'RENDER_FAILED', fatal: false }`. The package's console lines all start with `[Workflows]`, and a line that was
221
+ already said is not said again, so a screen that keeps failing does not fill a page's console.
222
+
223
+ A request to the API that fails (offline, refused, a server error) is told to the person by the screen itself, in their
224
+ language, and to the page with `{ code: 'REQUEST_FAILED', fatal: false }`. A session the API no longer accepts (the page's
225
+ `getAccessToken` could not give a token it takes) is `{ code: 'SESSION_ENDED' }`; the screen says the session ended. A
226
+ request the person cancelled on purpose (they left the screen) says nothing.
227
+
228
+ A boundary does not catch an error thrown in an event handler or after an `await`; those belong to the code that wrote
229
+ them.
230
+
231
+ ## Development
232
+
233
+ ```bash
234
+ npm install
235
+ npm run dev # the development page, with a language switcher
236
+ ```
237
+
238
+ More in [`__docs/how-to-run-on-localhost.md`](./__docs/how-to-run-on-localhost.md).
239
+
240
+ ### Sibling packages
241
+
242
+ This app compiles sibling `@widgetic/*` source in dev through the dev-alias setup `@widgetic/dev-tools` owns.
243
+ The alias tables, the `$lib` remap, and everything else the mapping needs come from the installed `@widgetic/dev-tools`
244
+ dependency. An ordinary `npm install` is the whole setup — there is no linking step.
245
+ The why and the silent-degrade failure mode live in [the dev-tools README](../dev-tools/README.md).
246
+
247
+ ### Tests
248
+
249
+ `npm test` runs the guards in Node, with no browser. Each one protects a promise the package makes to its hosts:
250
+
251
+ | File | What it protects |
252
+ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
253
+ | `tests/workflows-words.test.mjs` | The catalog: keys, English that people read first, templates, what a page's `messages` can do. |
254
+ | `tests/workflows-words-audit.test.mjs` | No sentence is written into a file; every key is used; the language reaches every part. |
255
+ | `tests/workflows-direction.test.mjs` | Nothing is placed on a physical side, so the screen mirrors; the root writes its direction. |
256
+ | `tests/workflows-theming.test.mjs` | No literal colour, font or corner: a theme has something to change. |
257
+ | `tests/workflows-logger.test.mjs` | Each console line is said once. |
258
+ | `tests/no-service-key.test.mjs` | No service key is read or sent from code that runs in a visitor's browser. |
259
+ | `tests/package-shape.test.mjs` | What `package.json` promises exists in `src/lib`; the CI publishes without a token in the repo. |
260
+ | `tests/workflows-api.test.mjs` | The API client: what it asks (address, token, the key that makes a retry safe), what it makes of each answer and how each way of failing is told apart. |
261
+ | `tests/workflows-editor-model.test.mjs` | Making and changing blocks, rules and tests; where a block goes; what a composition can do; the canvas adapter; the test run; time zones. |
262
+ | `tests/workflows-graph-diff.test.mjs` | What changed between two versions of a graph, as the small operations the canvas is told (a block comes, goes or changes; a line comes or goes). |
263
+ | `tests/workflows-autosave.test.mjs` | The draft saver: when a change is sent, that two saves are never on their way at once, that nothing typed during a save is lost, and what each failure leaves behind. |
264
+ | `tests/workflows-layout.test.mjs` | The screen fills the element the page gives it and scrolls inside it (`overflow-auto` on each root), so a short host is never painted over. |
265
+ | `tests/workflows-text.test.mjs` | The words around what a person built: issues, failed requests, block names, rule summaries, counts and days. |
266
+
267
+ Before a change is done: `npm run check` (0 errors, 0 warnings), `npm test`, `npm run lint` and `npm run package`.
268
+
269
+ ## Publishing
270
+
271
+ Publishing starts here: `npm run package` builds the `dist/` directory that is the only content the published tarball ships.
272
+ Linked consumers keep resolving this checkout’s files until the release lands, so a change is not real for anyone else until it publishes.
273
+ After publishing, each consumer package bumps its dependency to the new version and refreshes its lockfile with `npm install`, so `npm ci` resolves the release from the registry.
274
+ A consumer that skips the lockfile refresh keeps resolving the old version, so the version bump and the lockfile refresh land as one commit.
275
+
276
+ GitLab CI publishes from `main` through npm trusted publishing: the job gets a short-lived identity token
277
+ (`NPM_ID_TOKEN`) and there is no npm token in the repository. It publishes the `version` in `package.json` when that
278
+ version is not on npm yet, and skips it when it is.
279
+
280
+ **From a laptop** (while CI has no minutes left, and for the first version): `npm run publish-to-npm`, the shared script
281
+ of `@widgetic/dev-tools`, raises the patch, builds, publishes from your machine, commits the version files, tags the
282
+ release and pushes, so the CI then finds that version on npm and skips it. It needs a login that may publish the
283
+ `@widgetic` organisation: a granular token with Bypass 2FA in `~/.npmrc`, or a browser approval for each publish.
284
+
285
+ **The first release is made from a laptop.** npm only lets a trusted publisher be set up on a package that exists, so the
286
+ CI cannot publish the first version:
287
+
288
+ 1. A maintainer of the `@widgetic` npm organisation runs `npm run publish-to-npm` in this folder. The package starts at
289
+ `0.1.0` in `package.json` and the script raises the patch before it publishes, so the first version on npm is `0.1.1`.
290
+ The script builds `dist/` first, because the tarball ships nothing else and a version on npm can never be used again;
291
+ `npm publish --dry-run` shows the files it would ship, which is the check to make before the real one.
292
+ 2. On the package's npm settings page, under **Trusted Publisher** (or with `npm trust gitlab`), they choose **GitLab
293
+ CI/CD** and enter, with the case exactly as written: namespace `widgeticai/Frontend` (the full group path, subgroups
294
+ included), project name `workflows`, top-level CI file path `.gitlab-ci.yml`, and `npm publish` as an allowed action.
295
+ That last one matters: a configuration made after 3 September 2026 allows only `npm stage publish` until
296
+ `npm publish` is allowed, and the CI job runs `npm publish`. npm does not check the fields when they are saved, so a
297
+ wrong one shows up as `ENEEDAUTH` in the `publish` job.
298
+ 3. Within two days, the CI has to make a successful publish of its own, or npm drops the configuration (create it again
299
+ when the CI can run). A publish from a laptop is not this step, because it leaves the CI with nothing to publish:
300
+ raise `version`, commit and push `main` once the CI has minutes.
301
+ 4. From then on a push to `main` that raises the version publishes it.
302
+
303
+ ## License
304
+
305
+ Widgetic Integration License, version 1.0. See [LICENSE](./LICENSE).
@@ -0,0 +1,4 @@
1
+ import type { WorkflowsApi } from './workflowsApi.js';
2
+ export declare function provideWorkflowsApi(api: WorkflowsApi): WorkflowsApi;
3
+ /** Called by a part of the screen while it is created. The root makes the client before it draws anything that needs it. */
4
+ export declare function useWorkflowsApi(): WorkflowsApi;
@@ -0,0 +1,17 @@
1
+ import { getContext, setContext } from 'svelte';
2
+ /**
3
+ * The API client of the screen, shared with every part below the root (the list, the editor, the composition picker) through
4
+ * the component context, so that no part makes a client of its own: they all use the token function and the workspace the
5
+ * page gave the root, and a test hands in one client with a stand-in `fetch`.
6
+ */
7
+ const API_CONTEXT_KEY = Symbol('workflows-api');
8
+ export function provideWorkflowsApi(api) {
9
+ return setContext(API_CONTEXT_KEY, api);
10
+ }
11
+ /** Called by a part of the screen while it is created. The root makes the client before it draws anything that needs it. */
12
+ export function useWorkflowsApi() {
13
+ const api = getContext(API_CONTEXT_KEY);
14
+ if (!api)
15
+ throw new Error('[Workflows] A part of the screen was drawn without the API client of its root.');
16
+ return api;
17
+ }
@@ -0,0 +1,168 @@
1
+ /**
2
+ * What the Widgetic API says about workflows, as the screens use it. These are the shapes of the gateway's answers
3
+ * (`/v1/workspaces/{workspaceId}/workflows...`); the client in `workflowsApi.ts` checks each answer against them before a
4
+ * screen sees it, so a screen never has to ask "is this field really here".
5
+ *
6
+ * The graph itself (blocks, connections, rules) is the engine's: `@widgetic/workflows-engine` is the one place that knows
7
+ * what a workflow is, and the gateway, the embed and this package all read it from there.
8
+ */
9
+ import type { FieldType, ValidationIssue, WorkflowGraph } from '@widgetic/workflows-engine';
10
+ /** Where a workflow is in its life. A draft was never published; a live one serves visitors; paused serves only its first composition. */
11
+ export type WorkflowStatus = 'draft' | 'live' | 'paused' | 'archived';
12
+ export declare const WORKFLOW_STATUSES: readonly WorkflowStatus[];
13
+ /** The longest name a workflow can have: the gateway's own limit, so a name typed here is never refused for its length. */
14
+ export declare const MAX_WORKFLOW_NAME_LENGTH = 120;
15
+ /** What the list can be ordered by (the four columns it shows). */
16
+ export type WorkflowSortField = 'createdAt' | 'lastPublishedAt' | 'runsCount' | 'name';
17
+ export type SortDirection = 'asc' | 'desc';
18
+ /** A workflow as the list shows it. */
19
+ export interface WorkflowListItem {
20
+ id: string;
21
+ name: string;
22
+ status: WorkflowStatus;
23
+ /** The draft's revision: a save, a publish, a discard and a restore each name the one they started from. */
24
+ revision: number;
25
+ unpublishedChanges: boolean;
26
+ compositionIds: string[];
27
+ blockCount: number;
28
+ timezone: string;
29
+ /** Visitors who started it, over its whole life. */
30
+ runsCount: number;
31
+ liveVersionId: string | null;
32
+ createdAt: string;
33
+ updatedAt: string;
34
+ firstPublishedAt: string | null;
35
+ lastPublishedAt: string | null;
36
+ pausedAt: string | null;
37
+ archivedAt: string | null;
38
+ }
39
+ /** A published version, as the version history lists it. */
40
+ export interface WorkflowVersion {
41
+ id: string;
42
+ versionNumber: number;
43
+ publishedAt: string;
44
+ /** Who published it. `name` is null for a person without one, and the whole value is null once that account is gone. */
45
+ publishedBy: {
46
+ id: string;
47
+ name: string | null;
48
+ } | null;
49
+ timezone: string;
50
+ isLive: boolean;
51
+ }
52
+ /** A published version with its graph: the read-only preview and the Runs canvas draw it. */
53
+ export interface WorkflowVersionDetail extends WorkflowVersion {
54
+ startNodeId: string;
55
+ graph: WorkflowGraph;
56
+ }
57
+ /** One workflow with its draft. */
58
+ export interface WorkflowDetail extends WorkflowListItem {
59
+ graph: WorkflowGraph;
60
+ /** The version visitors get, without its graph; null before the first publish. */
61
+ liveVersion: WorkflowVersion | null;
62
+ /** Whether this workflow was ever published (it can then be archived but not deleted). */
63
+ everPublished: boolean;
64
+ }
65
+ export interface WorkflowList {
66
+ items: WorkflowListItem[];
67
+ total: number;
68
+ limit: number;
69
+ offset: number;
70
+ }
71
+ /** What publishing answered: the workflow as it is now, the version made, and advice that did not stop it. */
72
+ export interface WorkflowPublishResult {
73
+ workflow: WorkflowDetail;
74
+ version: WorkflowVersion;
75
+ warnings: ValidationIssue[];
76
+ }
77
+ /** One count per block, per connection and per composition that could not be shown, as lists (ids are values, never keys). */
78
+ export interface WorkflowStats {
79
+ workflowId: string;
80
+ versionId: string | null;
81
+ from: string;
82
+ to: string;
83
+ /** Visitors who started it in the range; null when the counts are for all versions. */
84
+ started: number | null;
85
+ nodes: Array<{
86
+ id: string;
87
+ total: number;
88
+ }>;
89
+ edges: Array<{
90
+ id: string;
91
+ total: number;
92
+ }>;
93
+ failed: Array<{
94
+ id: string;
95
+ total: number;
96
+ }>;
97
+ }
98
+ /** Why a trigger is not available on a composition. */
99
+ export type CapabilityReason = 'widget_keeps_no_data' | 'widget_reports_no_actions' | 'widget_not_published';
100
+ export interface CompositionOptionField {
101
+ table: string;
102
+ column: string;
103
+ label: string;
104
+ type: FieldType;
105
+ }
106
+ export interface CompositionOptionAction {
107
+ /** What the trigger stores to say which action it waits for. */
108
+ id: string;
109
+ metric: string;
110
+ label: string;
111
+ selector: string | null;
112
+ }
113
+ /** One composition as the editor offers it, with what it can feed into a workflow. */
114
+ export interface CompositionOption {
115
+ id: string;
116
+ name: string;
117
+ thumbnailUrl: string | null;
118
+ /** Whether the composition can be shown at all (its widget has a published version). */
119
+ published: boolean;
120
+ /** The websites the composition may be embedded on; empty means anywhere. */
121
+ allowedWebsites: string[];
122
+ inputs: {
123
+ enabled: boolean;
124
+ reason: CapabilityReason | null;
125
+ tables: string[];
126
+ fields: CompositionOptionField[];
127
+ };
128
+ actions: {
129
+ enabled: boolean;
130
+ reason: CapabilityReason | null;
131
+ items: CompositionOptionAction[];
132
+ };
133
+ }
134
+ export interface CompositionOptionList {
135
+ items: CompositionOption[];
136
+ total: number;
137
+ limit: number;
138
+ offset: number;
139
+ }
140
+ /** What the list asks for. Everything is optional: nothing asked is the first page, newest first, drafts, live and paused. */
141
+ export interface WorkflowListQuery {
142
+ search?: string;
143
+ /** `all` lists every state, archived included. */
144
+ status?: WorkflowStatus | 'all';
145
+ sort?: {
146
+ field: WorkflowSortField;
147
+ direction: SortDirection;
148
+ };
149
+ limit?: number;
150
+ offset?: number;
151
+ }
152
+ export interface CompositionOptionsQuery {
153
+ search?: string;
154
+ /** Only these compositions (those of them the person may see). */
155
+ ids?: readonly string[];
156
+ limit?: number;
157
+ offset?: number;
158
+ }
159
+ /** What the Runs tab asks for: one version (or all of them) and a range of days, written `YYYY-MM-DD`. */
160
+ export interface WorkflowStatsQuery {
161
+ versionId?: string;
162
+ from?: string;
163
+ to?: string;
164
+ }
165
+ /** The state changes a workflow goes through, one request each. */
166
+ export type WorkflowStateAction = 'pause' | 'resume' | 'archive' | 'unarchive';
167
+ /** The token function the host gives the screen (see `AccessTokenFunction` of the ui-sdk modules). */
168
+ export type AccessTokenFunction = (reason: 'initial' | 'expired', refusedToken?: string) => Promise<string> | string;
@@ -0,0 +1,3 @@
1
+ export const WORKFLOW_STATUSES = ['draft', 'live', 'paused', 'archived'];
2
+ /** The longest name a workflow can have: the gateway's own limit, so a name typed here is never refused for its length. */
3
+ export const MAX_WORKFLOW_NAME_LENGTH = 120;