@widgetic/workflows 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +107 -46
- package/dist/api/apiContext.d.ts +4 -0
- package/dist/api/apiContext.js +17 -0
- package/dist/api/types.d.ts +168 -0
- package/dist/api/types.js +3 -0
- package/dist/api/workflowsApi.d.ts +109 -0
- package/dist/api/workflowsApi.js +657 -0
- package/dist/components/Workflows.svelte +41 -17
- package/dist/components/WorkflowsEmptyState.svelte +16 -5
- package/dist/components/WorkflowsEmptyState.svelte.d.ts +5 -16
- package/dist/components/WorkflowsHeader.svelte +2 -2
- package/dist/components/WorkflowsWorkspace.svelte +87 -0
- package/dist/components/WorkflowsWorkspace.svelte.d.ts +14 -0
- package/dist/components/canvas/AddBlockMenu.svelte +101 -0
- package/dist/components/canvas/AddBlockMenu.svelte.d.ts +5 -0
- package/dist/components/canvas/CanvasToolbar.svelte +95 -0
- package/dist/components/canvas/CanvasToolbar.svelte.d.ts +9 -0
- package/dist/components/canvas/CompositionNodeView.svelte +125 -0
- package/dist/components/canvas/CompositionNodeView.svelte.d.ts +5 -0
- package/dist/components/canvas/ConditionNodeView.svelte +95 -0
- package/dist/components/canvas/ConditionNodeView.svelte.d.ts +5 -0
- package/dist/components/canvas/HandlePoint.svelte +32 -0
- package/dist/components/canvas/HandlePoint.svelte.d.ts +14 -0
- package/dist/components/canvas/TriggerNodeView.svelte +75 -0
- package/dist/components/canvas/TriggerNodeView.svelte.d.ts +5 -0
- package/dist/components/canvas/WorkflowCanvas.svelte +380 -0
- package/dist/components/canvas/WorkflowCanvas.svelte.d.ts +25 -0
- package/dist/components/canvas/WorkflowEdgeView.svelte +58 -0
- package/dist/components/canvas/WorkflowEdgeView.svelte.d.ts +4 -0
- package/dist/components/editor/EditorBanners.svelte +143 -0
- package/dist/components/editor/EditorBanners.svelte.d.ts +7 -0
- package/dist/components/editor/EditorCanvasArea.svelte +85 -0
- package/dist/components/editor/EditorCanvasArea.svelte.d.ts +3 -0
- package/dist/components/editor/EditorTabs.svelte +81 -0
- package/dist/components/editor/EditorTabs.svelte.d.ts +7 -0
- package/dist/components/editor/EditorTopBar.svelte +132 -0
- package/dist/components/editor/EditorTopBar.svelte.d.ts +9 -0
- package/dist/components/editor/RunsTab.svelte +256 -0
- package/dist/components/editor/RunsTab.svelte.d.ts +3 -0
- package/dist/components/editor/SettingsTab.svelte +180 -0
- package/dist/components/editor/SettingsTab.svelte.d.ts +7 -0
- package/dist/components/editor/WorkflowEditor.svelte +185 -0
- package/dist/components/editor/WorkflowEditor.svelte.d.ts +15 -0
- package/dist/components/index.d.ts +0 -2
- package/dist/components/index.js +0 -2
- package/dist/components/list/CreateWorkflowDialog.svelte +89 -0
- package/dist/components/list/CreateWorkflowDialog.svelte.d.ts +9 -0
- package/dist/components/list/WorkflowList.svelte +204 -0
- package/dist/components/list/WorkflowList.svelte.d.ts +12 -0
- package/dist/components/list/WorkflowRow.svelte +191 -0
- package/dist/components/list/WorkflowRow.svelte.d.ts +10 -0
- package/dist/components/panel/BlockProblems.svelte +47 -0
- package/dist/components/panel/BlockProblems.svelte.d.ts +6 -0
- package/dist/components/panel/CompositionForm.svelte +127 -0
- package/dist/components/panel/CompositionForm.svelte.d.ts +7 -0
- package/dist/components/panel/CompositionPicker.svelte +179 -0
- package/dist/components/panel/CompositionPicker.svelte.d.ts +14 -0
- package/dist/components/panel/ConditionForm.svelte +105 -0
- package/dist/components/panel/ConditionForm.svelte.d.ts +7 -0
- package/dist/components/panel/EventValueRow.svelte +85 -0
- package/dist/components/panel/EventValueRow.svelte.d.ts +12 -0
- package/dist/components/panel/NextStepSelect.svelte +70 -0
- package/dist/components/panel/NextStepSelect.svelte.d.ts +12 -0
- package/dist/components/panel/ProblemsList.svelte +101 -0
- package/dist/components/panel/ProblemsList.svelte.d.ts +3 -0
- package/dist/components/panel/RuleCard.svelte +191 -0
- package/dist/components/panel/RuleCard.svelte.d.ts +13 -0
- package/dist/components/panel/SidePanel.svelte +82 -0
- package/dist/components/panel/SidePanel.svelte.d.ts +3 -0
- package/dist/components/panel/TestRow.svelte +150 -0
- package/dist/components/panel/TestRow.svelte.d.ts +15 -0
- package/dist/components/panel/TestRunPanel.svelte +85 -0
- package/dist/components/panel/TestRunPanel.svelte.d.ts +3 -0
- package/dist/components/panel/TestTriggerCard.svelte +121 -0
- package/dist/components/panel/TestTriggerCard.svelte.d.ts +7 -0
- package/dist/components/panel/TriggerForm.svelte +385 -0
- package/dist/components/panel/TriggerForm.svelte.d.ts +7 -0
- package/dist/components/panel/VersionHistory.svelte +123 -0
- package/dist/components/panel/VersionHistory.svelte.d.ts +3 -0
- package/dist/components/ui/ActionButton.svelte +85 -0
- package/dist/components/ui/ActionButton.svelte.d.ts +27 -0
- package/dist/components/ui/ConfirmDialog.svelte +52 -0
- package/dist/components/ui/ConfirmDialog.svelte.d.ts +16 -0
- package/dist/components/ui/Icon.svelte +32 -0
- package/dist/components/ui/Icon.svelte.d.ts +9 -0
- package/dist/components/ui/Menu.svelte +211 -0
- package/dist/components/ui/Menu.svelte.d.ts +21 -0
- package/dist/components/ui/Modal.svelte +129 -0
- package/dist/components/ui/Modal.svelte.d.ts +13 -0
- package/dist/components/ui/Notice.svelte +36 -0
- package/dist/components/ui/Notice.svelte.d.ts +11 -0
- package/dist/components/ui/SelectField.svelte +74 -0
- package/dist/components/ui/SelectField.svelte.d.ts +16 -0
- package/dist/components/ui/StatusBadge.svelte +41 -0
- package/dist/components/ui/StatusBadge.svelte.d.ts +9 -0
- package/dist/components/ui/TextField.svelte +97 -0
- package/dist/components/ui/TextField.svelte.d.ts +29 -0
- package/dist/components/ui/icons.d.ts +34 -0
- package/dist/components/ui/icons.js +54 -0
- package/dist/components/ui/types.d.ts +26 -0
- package/dist/components/ui/types.js +1 -0
- package/dist/editor/apiErrorText.d.ts +10 -0
- package/dist/editor/apiErrorText.js +53 -0
- package/dist/editor/autosave.d.ts +47 -0
- package/dist/editor/autosave.js +119 -0
- package/dist/editor/blockLabels.d.ts +91 -0
- package/dist/editor/blockLabels.js +196 -0
- package/dist/editor/canvasContext.d.ts +52 -0
- package/dist/editor/canvasContext.js +37 -0
- package/dist/editor/canvasWords.d.ts +24 -0
- package/dist/editor/canvasWords.js +40 -0
- package/dist/editor/capabilityModel.d.ts +46 -0
- package/dist/editor/capabilityModel.js +113 -0
- package/dist/editor/editorState.svelte.d.ts +220 -0
- package/dist/editor/editorState.svelte.js +713 -0
- package/dist/editor/flowAdapter.d.ts +59 -0
- package/dist/editor/flowAdapter.js +166 -0
- package/dist/editor/formatCount.d.ts +5 -0
- package/dist/editor/formatCount.js +15 -0
- package/dist/editor/graphDiff.d.ts +27 -0
- package/dist/editor/graphDiff.js +64 -0
- package/dist/editor/graphModel.d.ts +154 -0
- package/dist/editor/graphModel.js +457 -0
- package/dist/editor/issueText.d.ts +64 -0
- package/dist/editor/issueText.js +101 -0
- package/dist/editor/listState.svelte.d.ts +82 -0
- package/dist/editor/listState.svelte.js +250 -0
- package/dist/editor/statsRange.d.ts +26 -0
- package/dist/editor/statsRange.js +41 -0
- package/dist/editor/testRun.d.ts +36 -0
- package/dist/editor/testRun.js +74 -0
- package/dist/editor/zonedTime.d.ts +20 -0
- package/dist/editor/zonedTime.js +134 -0
- package/dist/i18n/language.d.ts +3 -3
- package/dist/i18n/messages.d.ts +396 -4
- package/dist/i18n/messages.js +421 -8
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -1
- package/dist/types/index.d.ts +31 -3
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -3,16 +3,38 @@
|
|
|
3
3
|
Workflows for Widgetic: chain compositions together, with filters between them that decide which composition an embed
|
|
4
4
|
shows. One Svelte package that the Widgetic site, partners and Shopify all load.
|
|
5
5
|
|
|
6
|
-
> **Status:
|
|
7
|
-
>
|
|
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
|
|
8
9
|
> [`__docs/concepts.md`](./__docs/concepts.md).
|
|
9
10
|
|
|
10
11
|
Workflows are for **Teams and partner accounts** only. On Widgetic the page is
|
|
11
12
|
`/workspaces/<workspace>/experiments/workflows`, below _Translations_ in the sidebar.
|
|
12
13
|
|
|
13
|
-
## What it does
|
|
14
|
-
|
|
15
|
-
-
|
|
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.
|
|
16
38
|
- Speaks the page's language (`locale`, `messages`) and turns around for right to left (`dir`).
|
|
17
39
|
- Takes its colours, font and corners from CSS custom properties, so a host or a ui-sdk theme restyles it.
|
|
18
40
|
- Reports what goes wrong to the page (`onError`) and shows the visitor a "Try again" in place of a part that failed.
|
|
@@ -53,12 +75,22 @@ has to read the package, or the screen is drawn without its classes. In the host
|
|
|
53
75
|
|
|
54
76
|
const locale = 'ar';
|
|
55
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
|
+
}
|
|
56
83
|
</script>
|
|
57
84
|
|
|
58
85
|
<Workflows
|
|
86
|
+
apiUrl="https://api.widgetic.com"
|
|
87
|
+
{getAccessToken}
|
|
88
|
+
workspaceId="personal"
|
|
59
89
|
{locale}
|
|
60
90
|
messages={arabicMessages}
|
|
61
91
|
dir={resolveTextDirection(locale)}
|
|
92
|
+
onOpenWorkflow={(workflowId) =>
|
|
93
|
+
history.pushState(null, '', workflowId ? `/workflows/${workflowId}` : '/workflows')}
|
|
62
94
|
onError={(error) => console.warn(error.code, error.message)}
|
|
63
95
|
/>
|
|
64
96
|
```
|
|
@@ -68,18 +100,29 @@ the screen needs, the screen scrolls inside it; it never spills over what the pa
|
|
|
68
100
|
|
|
69
101
|
### Props
|
|
70
102
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
|
|
81
|
-
`
|
|
82
|
-
|
|
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.
|
|
83
126
|
|
|
84
127
|
## Look and feel
|
|
85
128
|
|
|
@@ -87,15 +130,16 @@ Nothing in the screen is a literal colour, font or corner. It reads the Widgetic
|
|
|
87
130
|
those values set as CSS custom properties on an element that contains the screen. A colour is three numbers (hue,
|
|
88
131
|
saturation, lightness) with no `hsl()` around them, because the components write `hsl(var(--grey2))`.
|
|
89
132
|
|
|
90
|
-
| Property
|
|
91
|
-
|
|
|
92
|
-
| `--ink-primary`
|
|
93
|
-
| `--ink-muted`
|
|
94
|
-
| `--
|
|
95
|
-
| `--
|
|
96
|
-
| `--
|
|
97
|
-
| `--
|
|
98
|
-
| `--
|
|
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. |
|
|
99
143
|
|
|
100
144
|
```css
|
|
101
145
|
.my-workflows-host {
|
|
@@ -128,17 +172,23 @@ Every word a person reads is a message in a catalog of English sentences, `WORKF
|
|
|
128
172
|
`workflows.<where>.<what>`. A page gives its own words with `messages`; what it leaves out stays English, so a language
|
|
129
173
|
can be added a screen at a time.
|
|
130
174
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
|
134
|
-
|
|
|
135
|
-
| `workflows.header
|
|
136
|
-
| `workflows.
|
|
137
|
-
| `workflows.
|
|
138
|
-
| `workflows.
|
|
139
|
-
| `workflows.
|
|
140
|
-
| `workflows.
|
|
141
|
-
| `workflows.
|
|
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.
|
|
142
192
|
|
|
143
193
|
A message is plain text. `{name}` is a value the screen puts in, and
|
|
144
194
|
`{count, plural, one {# step} other {# steps}}` picks the form that fits a number in the page's language. The whole
|
|
@@ -170,6 +220,11 @@ not be shown" with a **Try again** button in its place, and the page's `onError`
|
|
|
170
220
|
`{ code: 'RENDER_FAILED', fatal: false }`. The package's console lines all start with `[Workflows]`, and a line that was
|
|
171
221
|
already said is not said again, so a screen that keeps failing does not fill a page's console.
|
|
172
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
|
+
|
|
173
228
|
A boundary does not catch an error thrown in an event handler or after an `await`; those belong to the code that wrote
|
|
174
229
|
them.
|
|
175
230
|
|
|
@@ -193,15 +248,21 @@ The why and the silent-degrade failure mode live in [the dev-tools README](../de
|
|
|
193
248
|
|
|
194
249
|
`npm test` runs the guards in Node, with no browser. Each one protects a promise the package makes to its hosts:
|
|
195
250
|
|
|
196
|
-
| File
|
|
197
|
-
|
|
|
198
|
-
| `tests/workflows-words.test.mjs`
|
|
199
|
-
| `tests/workflows-words-audit.test.mjs`
|
|
200
|
-
| `tests/workflows-direction.test.mjs`
|
|
201
|
-
| `tests/workflows-theming.test.mjs`
|
|
202
|
-
| `tests/workflows-logger.test.mjs`
|
|
203
|
-
| `tests/no-service-key.test.mjs`
|
|
204
|
-
| `tests/package-shape.test.mjs`
|
|
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. |
|
|
205
266
|
|
|
206
267
|
Before a change is done: `npm run check` (0 errors, 0 warnings), `npm test`, `npm run lint` and `npm run package`.
|
|
207
268
|
|
|
@@ -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,109 @@
|
|
|
1
|
+
import type { IssueCode, ValidationIssue, WorkflowGraph } from '@widgetic/workflows-engine';
|
|
2
|
+
import { type AccessTokenFunction, type CompositionOption, type CompositionOptionList, type CompositionOptionsQuery, type WorkflowDetail, type WorkflowList, type WorkflowListItem, type WorkflowListQuery, type WorkflowPublishResult, type WorkflowStateAction, type WorkflowStats, type WorkflowStatsQuery, type WorkflowVersion, type WorkflowVersionDetail } from './types.js';
|
|
3
|
+
/** How long a request may take before it is given up: the reads, and the writes (a publish reads every composition). */
|
|
4
|
+
export declare const READ_TIMEOUT_MS = 15000;
|
|
5
|
+
export declare const WRITE_TIMEOUT_MS = 30000;
|
|
6
|
+
/** What went wrong with a request, as far as the screens care. */
|
|
7
|
+
export declare class WorkflowsApiError extends Error {
|
|
8
|
+
/** The HTTP status; null when no answer came (offline, blocked by the page's policy, too slow, a token that could not be had). */
|
|
9
|
+
readonly status: number | null;
|
|
10
|
+
/**
|
|
11
|
+
* The API's error code (`BUSINESS_STATE_CONFLICT`, `AUTHZ_PLAN_RESTRICTION`...), or the screen's own: `NETWORK_ERROR`,
|
|
12
|
+
* `TIMEOUT`, `TOKEN_UNAVAILABLE`, `INVALID_RESPONSE`, or `HTTP_<status>` when the answer carried no code.
|
|
13
|
+
*/
|
|
14
|
+
readonly code: string;
|
|
15
|
+
/** What the API said besides (`reason`, `currentRevision`, `issues`...), as it came; null when it said nothing more. */
|
|
16
|
+
readonly details: Record<string, unknown> | null;
|
|
17
|
+
constructor(message: string, details: {
|
|
18
|
+
status: number | null;
|
|
19
|
+
code: string;
|
|
20
|
+
details?: Record<string, unknown> | null;
|
|
21
|
+
cause?: unknown;
|
|
22
|
+
});
|
|
23
|
+
/** The person's session is over: the API refused the token, and the fresh one too. */
|
|
24
|
+
get sessionEnded(): boolean;
|
|
25
|
+
/** The account's plan does not include workflows. */
|
|
26
|
+
get planRestricted(): boolean;
|
|
27
|
+
/** The workflow, version or composition is not there (any more). */
|
|
28
|
+
get notFound(): boolean;
|
|
29
|
+
/** Somebody saved the draft since this screen read it: the screen reloads, it never overwrites. */
|
|
30
|
+
get revisionChanged(): boolean;
|
|
31
|
+
/** The revision the draft is at now, when the API said (a refused save or publish). */
|
|
32
|
+
get currentRevision(): number | null;
|
|
33
|
+
/** Why a 409 was refused (`revision_changed`, `nothing_to_publish`, `nothing_to_discard`, `workflow_archived`, `wrong_state`). */
|
|
34
|
+
get conflictReason(): string | null;
|
|
35
|
+
/** What stopped a publish (422) or a save of a document the engine cannot read (400): the blocks to fix. */
|
|
36
|
+
get issues(): ValidationIssue[];
|
|
37
|
+
}
|
|
38
|
+
/** Whether an error is a request that was cancelled on purpose (the screen was taken down). */
|
|
39
|
+
export declare function isCancelled(error: unknown): boolean;
|
|
40
|
+
export interface WorkflowsApiOptions {
|
|
41
|
+
/** The Widgetic API origin, without `/v1` (the module's `apiUrl`). */
|
|
42
|
+
apiUrl: string;
|
|
43
|
+
/** `personal`, or an organization id. */
|
|
44
|
+
workspaceId: string;
|
|
45
|
+
getAccessToken: AccessTokenFunction;
|
|
46
|
+
/** For tests. The page's `fetch` by default. */
|
|
47
|
+
fetchImplementation?: typeof fetch;
|
|
48
|
+
/** For tests. */
|
|
49
|
+
readTimeoutMs?: number;
|
|
50
|
+
writeTimeoutMs?: number;
|
|
51
|
+
}
|
|
52
|
+
export interface RequestOptions {
|
|
53
|
+
signal?: AbortSignal;
|
|
54
|
+
}
|
|
55
|
+
/** The writes that must not happen twice when an answer is lost. */
|
|
56
|
+
export interface RetryableRequestOptions extends RequestOptions {
|
|
57
|
+
/**
|
|
58
|
+
* The key that makes a retry of this request safe: the same key replays the answer of a request that was made. Made
|
|
59
|
+
* when left out.
|
|
60
|
+
*/
|
|
61
|
+
idempotencyKey?: string;
|
|
62
|
+
}
|
|
63
|
+
export interface WorkflowsApi {
|
|
64
|
+
listWorkflows(query?: WorkflowListQuery, options?: RequestOptions): Promise<WorkflowList>;
|
|
65
|
+
createWorkflow(input: {
|
|
66
|
+
name: string;
|
|
67
|
+
compositionId?: string | null;
|
|
68
|
+
timezone?: string | null;
|
|
69
|
+
}, options?: RetryableRequestOptions): Promise<WorkflowDetail>;
|
|
70
|
+
getWorkflow(workflowId: string, options?: RequestOptions): Promise<WorkflowDetail>;
|
|
71
|
+
/** Saves the draft; answers the workflow's list entry with the new revision. */
|
|
72
|
+
saveDraft(workflowId: string, input: {
|
|
73
|
+
revision: number;
|
|
74
|
+
name?: string;
|
|
75
|
+
timezone?: string;
|
|
76
|
+
graph?: WorkflowGraph;
|
|
77
|
+
}, options?: RequestOptions): Promise<WorkflowListItem>;
|
|
78
|
+
deleteWorkflow(workflowId: string, options?: RequestOptions): Promise<void>;
|
|
79
|
+
duplicateWorkflow(workflowId: string, options?: RetryableRequestOptions): Promise<WorkflowDetail>;
|
|
80
|
+
publishWorkflow(workflowId: string, revision: number, options?: RetryableRequestOptions): Promise<WorkflowPublishResult>;
|
|
81
|
+
discardChanges(workflowId: string, revision: number, options?: RequestOptions): Promise<WorkflowDetail>;
|
|
82
|
+
listVersions(workflowId: string, options?: RequestOptions): Promise<WorkflowVersion[]>;
|
|
83
|
+
getVersion(workflowId: string, versionId: string, options?: RequestOptions): Promise<WorkflowVersionDetail>;
|
|
84
|
+
restoreVersion(workflowId: string, versionId: string, revision: number, options?: RequestOptions): Promise<WorkflowDetail>;
|
|
85
|
+
changeState(workflowId: string, action: WorkflowStateAction, options?: RequestOptions): Promise<WorkflowListItem>;
|
|
86
|
+
getStats(workflowId: string, query?: WorkflowStatsQuery, options?: RequestOptions): Promise<WorkflowStats>;
|
|
87
|
+
listCompositionOptions(query?: CompositionOptionsQuery, options?: RequestOptions): Promise<CompositionOptionList>;
|
|
88
|
+
}
|
|
89
|
+
/** A key the gateway accepts as an `Idempotency-Key` (`^[A-Za-z0-9_-]{8,50}$`). */
|
|
90
|
+
export declare function makeIdempotencyKey(): string;
|
|
91
|
+
/** One workflow of the list (or the same fields of a workflow in full). */
|
|
92
|
+
export declare function readWorkflowListItem(data: unknown): WorkflowListItem;
|
|
93
|
+
export declare function readWorkflowVersion(data: unknown): WorkflowVersion;
|
|
94
|
+
export declare function readWorkflowVersionDetail(data: unknown): WorkflowVersionDetail;
|
|
95
|
+
export declare function readWorkflowDetail(data: unknown): WorkflowDetail;
|
|
96
|
+
/** The address of a thumbnail, when it is one an `<img>` should be given: http or https, nothing else. */
|
|
97
|
+
export declare function usableImageUrl(value: unknown): string | null;
|
|
98
|
+
/**
|
|
99
|
+
* One composition the editor can offer. What a composition cannot do reads as "not enabled" and never as an error: the
|
|
100
|
+
* capability model is the API's, and an answer that left a part out is treated as "this composition cannot do that".
|
|
101
|
+
*/
|
|
102
|
+
export declare function readCompositionOption(data: unknown): CompositionOption;
|
|
103
|
+
/** The query string of the list: only what was asked for. */
|
|
104
|
+
export declare function buildListQueryString(query: WorkflowListQuery | undefined): string;
|
|
105
|
+
export declare function buildCompositionOptionsQueryString(query: CompositionOptionsQuery | undefined): string;
|
|
106
|
+
/** Makes the client of one screen: one workspace, one way to get a token. */
|
|
107
|
+
export declare function createWorkflowsApi(options: WorkflowsApiOptions): WorkflowsApi;
|
|
108
|
+
/** The engine's issue codes a screen can say; re-exported so a screen imports one place. */
|
|
109
|
+
export type { IssueCode };
|