@widgetic/workflows 0.0.0-stage → 0.1.1

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/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,244 @@
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: V1, the shell.** The screen, its words, its theming and its release path exist. The editor, the data and
7
+ > the runs do not yet. What is planned, and the line between a workflow and the Embed SDK, is in
8
+ > [`__docs/concepts.md`](./__docs/concepts.md).
9
+
10
+ Workflows are for **Teams and partner accounts** only. On Widgetic the page is
11
+ `/workspaces/<workspace>/experiments/workflows`, below _Translations_ in the sidebar.
12
+
13
+ ## What it does today
14
+
15
+ - Draws the workflows screen: a header and a "No workflows yet" state.
16
+ - Speaks the page's language (`locale`, `messages`) and turns around for right to left (`dir`).
17
+ - Takes its colours, font and corners from CSS custom properties, so a host or a ui-sdk theme restyles it.
18
+ - Reports what goes wrong to the page (`onError`) and shows the visitor a "Try again" in place of a part that failed.
19
+
20
+ ## Where it is loaded
21
+
22
+ | Host | How |
23
+ | ------------- | ------------------------------------------------------------------------------------------------- |
24
+ | Widgetic site | `import { Workflows } from '@widgetic/workflows'` on the page, as it does for chat and editor |
25
+ | Partners | The `workflows` module of `@widgetic/ui-sdk`, loaded from the CDN with `ui.mount('workflows', …)` |
26
+ | Shopify | The same ui-sdk module, through a host component (later) |
27
+
28
+ How the three fit together, and the order they are released in: [`__docs/package-chain.md`](./__docs/package-chain.md).
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ npm install @widgetic/workflows @widgetic/design-system svelte
34
+ ```
35
+
36
+ `@widgetic/design-system` and `svelte` are peer dependencies. The host brings them, so there is one copy of each on the
37
+ page. The package needs Svelte 5.
38
+
39
+ **Styles.** The components are styled with Tailwind classes and ship no stylesheet of their own, so the host's Tailwind
40
+ has to read the package, or the screen is drawn without its classes. In the host's CSS, after the design system:
41
+
42
+ ```css
43
+ @import '@widgetic/design-system/styles';
44
+ @source '../node_modules/@widgetic/workflows/dist'; /* the path is relative to this CSS file */
45
+ ```
46
+
47
+ ## Use
48
+
49
+ ```svelte
50
+ <script lang="ts">
51
+ import { Workflows } from '@widgetic/workflows';
52
+ import { resolveTextDirection } from '@widgetic/design-system/i18n';
53
+
54
+ const locale = 'ar';
55
+ const arabicMessages = { 'workflows.header.title': 'سير العمل' };
56
+ </script>
57
+
58
+ <Workflows
59
+ {locale}
60
+ messages={arabicMessages}
61
+ dir={resolveTextDirection(locale)}
62
+ onError={(error) => console.warn(error.code, error.message)}
63
+ />
64
+ ```
65
+
66
+ The screen fills the height and width of the element it sits in. Give that element a size. When the element is shorter than
67
+ the screen needs, the screen scrolls inside it; it never spills over what the page has below.
68
+
69
+ ### Props
70
+
71
+ All of them are optional: a bare `<Workflows />` is a screen in English.
72
+
73
+ | Prop | Type | Default | What it does |
74
+ | ---------- | ------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
75
+ | `locale` | `string \| null` | English | A BCP 47 tag (`de`, `pt-BR`): plural rules, how numbers and dates are written. Translates nothing. |
76
+ | `messages` | `Readonly<Record<string, unknown>> \| null` | none | Your own words, by key. A key you leave out stays English. |
77
+ | `dir` | `'ltr' \| 'rtl'` | the screen around it | Which way the screen is read. You decide it; it is not worked out from `locale`. |
78
+ | `class` | `string` | `''` | Extra classes on the root element. |
79
+ | `onError` | `(error: WorkflowsError) => void` | none | Called once for each failure. |
80
+
81
+ `WorkflowsError` is `{ message: string; code: 'RENDER_FAILED'; fatal: boolean }`. The `message` is English, for the
82
+ page's developer. It is not a sentence to show a visitor: the screen shows its own.
83
+
84
+ ## Look and feel
85
+
86
+ Nothing in the screen is a literal colour, font or corner. It reads the Widgetic palette, and a theme is a handful of
87
+ those values set as CSS custom properties on an element that contains the screen. A colour is three numbers (hue,
88
+ saturation, lightness) with no `hsl()` around them, because the components write `hsl(var(--grey2))`.
89
+
90
+ | Property | What it paints |
91
+ | ----------------------------------- | ------------------------------------------------- |
92
+ | `--ink-primary` | The title and the text. |
93
+ | `--ink-muted` | The line under the title and the hints. |
94
+ | `--grey2` | The dashed border of the empty state. |
95
+ | `--primary-green` | The brand colour: the "Try again" button. |
96
+ | `--error` | The title of the failure state. |
97
+ | `--radius-medium`, `--radius-large` | The corners of the button and of the empty state. |
98
+ | `--font-sans` | The typeface. |
99
+
100
+ ```css
101
+ .my-workflows-host {
102
+ --primary-green: 262 83% 50%;
103
+ --ink-primary: 262 60% 14%;
104
+ --ink-muted: 262 20% 40%;
105
+ --grey2: 262 45% 80%;
106
+ --radius-large: 2px;
107
+ --font-sans: Georgia, serif;
108
+ }
109
+ ```
110
+
111
+ The surface is white (`bg-white`). Inside a ui-sdk module it follows the theme's `background`.
112
+
113
+ **For partners** the module takes a `theme` (a preset or `{ colors, radius, font }`), and the module spreads it over
114
+ these properties, so a partner never writes one by hand.
115
+
116
+ **For the people who write this package:** a colour, a font or a corner in a component is a token, never a literal.
117
+ `tests/workflows-theming.test.mjs` fails on a hex colour, a colour function, a colour of Tailwind's own palette, an
118
+ arbitrary value or a `style` attribute, and says what to write instead. Placement uses the start and the end of a line
119
+ (`ms-`, `me-`, `text-start`), never a physical side; `tests/workflows-direction.test.mjs` fails on `ml-`, `left-` and
120
+ the like unless the line says why with the note `rtl-ok`.
121
+
122
+ The shadcn names (`--background`, `--foreground`, `--muted`) are **not** what this package reads. The Widgetic site does
123
+ not define them, so a screen written against them would have no colour there.
124
+
125
+ ## Languages
126
+
127
+ Every word a person reads is a message in a catalog of English sentences, `WORKFLOWS_MESSAGES`, keyed
128
+ `workflows.<where>.<what>`. A page gives its own words with `messages`; what it leaves out stays English, so a language
129
+ can be added a screen at a time.
130
+
131
+ | Key | English |
132
+ | ---------------------------- | --------------------------------------------------------------------------------------------------- |
133
+ | `workflows.region.label` | Workflows |
134
+ | `workflows.header.title` | Workflows |
135
+ | `workflows.header.subtitle` | Decide which composition your embed shows, step by step. |
136
+ | `workflows.empty.title` | No workflows yet |
137
+ | `workflows.empty.hint` | A workflow chains compositions together. Filters between them decide which one a visitor sees next. |
138
+ | `workflows.empty.comingSoon` | Workflows are on their way. You will be able to build them here. |
139
+ | `workflows.error.title` | Workflows could not be shown |
140
+ | `workflows.error.hint` | Something went wrong while this screen was being drawn. |
141
+ | `workflows.error.retry` | Try again |
142
+
143
+ A message is plain text. `{name}` is a value the screen puts in, and
144
+ `{count, plural, one {# step} other {# steps}}` picks the form that fits a number in the page's language. The whole
145
+ format is described in `@widgetic/design-system/i18n`. A message is never written into the page as HTML.
146
+
147
+ Check your words before a visitor does:
148
+
149
+ ```ts
150
+ import { checkWorkflowsMessages } from '@widgetic/workflows';
151
+
152
+ // [] when every message will be used; otherwise a list that names each mistake
153
+ // (a key that does not exist, with the nearest real one; a template that does not parse)
154
+ console.log(checkWorkflowsMessages({ 'workflows.header.titel': 'Workflows' }));
155
+ ```
156
+
157
+ **The package ships English only; the other languages are packs of the module.** The twelve languages that the other
158
+ `@widgetic/ui-sdk` modules ship (`fr`, `de`, `es`, `pt-BR`, `nl`, `da`, `sv`, `zh-CN`, `ar`, `he`, `fa`, `ur`) are lazy
159
+ packs of the `workflows` module: the module loads the pack for the page's `locale` and hands it to this package as
160
+ `messages`, so a partner chooses a language with `locale` alone. A host that loads this package directly, as the
161
+ Widgetic site does, passes `messages` itself.
162
+
163
+ **Right to left.** Pass `dir="rtl"` (`resolveTextDirection(locale)` answers it for a language tag). The screen mirrors by
164
+ itself: everything is placed by the start and end of a line.
165
+
166
+ ## Errors
167
+
168
+ A part of the screen that throws while it is drawn is caught by a `<svelte:boundary>`. The screen shows "Workflows could
169
+ not be shown" with a **Try again** button in its place, and the page's `onError` is called once with
170
+ `{ code: 'RENDER_FAILED', fatal: false }`. The package's console lines all start with `[Workflows]`, and a line that was
171
+ already said is not said again, so a screen that keeps failing does not fill a page's console.
172
+
173
+ A boundary does not catch an error thrown in an event handler or after an `await`; those belong to the code that wrote
174
+ them.
175
+
176
+ ## Development
177
+
178
+ ```bash
179
+ npm install
180
+ npm run dev # the development page, with a language switcher
181
+ ```
182
+
183
+ More in [`__docs/how-to-run-on-localhost.md`](./__docs/how-to-run-on-localhost.md).
184
+
185
+ ### Sibling packages
186
+
187
+ This app compiles sibling `@widgetic/*` source in dev through the dev-alias setup `@widgetic/dev-tools` owns.
188
+ The alias tables, the `$lib` remap, and everything else the mapping needs come from the installed `@widgetic/dev-tools`
189
+ dependency. An ordinary `npm install` is the whole setup — there is no linking step.
190
+ The why and the silent-degrade failure mode live in [the dev-tools README](../dev-tools/README.md).
191
+
192
+ ### Tests
193
+
194
+ `npm test` runs the guards in Node, with no browser. Each one protects a promise the package makes to its hosts:
195
+
196
+ | File | What it protects |
197
+ | -------------------------------------- | ----------------------------------------------------------------------------------------------- |
198
+ | `tests/workflows-words.test.mjs` | The catalog: keys, English that people read first, templates, what a page's `messages` can do. |
199
+ | `tests/workflows-words-audit.test.mjs` | No sentence is written into a file; every key is used; the language reaches every part. |
200
+ | `tests/workflows-direction.test.mjs` | Nothing is placed on a physical side, so the screen mirrors; the root writes its direction. |
201
+ | `tests/workflows-theming.test.mjs` | No literal colour, font or corner: a theme has something to change. |
202
+ | `tests/workflows-logger.test.mjs` | Each console line is said once. |
203
+ | `tests/no-service-key.test.mjs` | No service key is read or sent from code that runs in a visitor's browser. |
204
+ | `tests/package-shape.test.mjs` | What `package.json` promises exists in `src/lib`; the CI publishes without a token in the repo. |
205
+
206
+ Before a change is done: `npm run check` (0 errors, 0 warnings), `npm test`, `npm run lint` and `npm run package`.
207
+
208
+ ## Publishing
209
+
210
+ Publishing starts here: `npm run package` builds the `dist/` directory that is the only content the published tarball ships.
211
+ Linked consumers keep resolving this checkout’s files until the release lands, so a change is not real for anyone else until it publishes.
212
+ 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.
213
+ A consumer that skips the lockfile refresh keeps resolving the old version, so the version bump and the lockfile refresh land as one commit.
214
+
215
+ GitLab CI publishes from `main` through npm trusted publishing: the job gets a short-lived identity token
216
+ (`NPM_ID_TOKEN`) and there is no npm token in the repository. It publishes the `version` in `package.json` when that
217
+ version is not on npm yet, and skips it when it is.
218
+
219
+ **From a laptop** (while CI has no minutes left, and for the first version): `npm run publish-to-npm`, the shared script
220
+ of `@widgetic/dev-tools`, raises the patch, builds, publishes from your machine, commits the version files, tags the
221
+ release and pushes, so the CI then finds that version on npm and skips it. It needs a login that may publish the
222
+ `@widgetic` organisation: a granular token with Bypass 2FA in `~/.npmrc`, or a browser approval for each publish.
223
+
224
+ **The first release is made from a laptop.** npm only lets a trusted publisher be set up on a package that exists, so the
225
+ CI cannot publish the first version:
226
+
227
+ 1. A maintainer of the `@widgetic` npm organisation runs `npm run publish-to-npm` in this folder. The package starts at
228
+ `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`.
229
+ The script builds `dist/` first, because the tarball ships nothing else and a version on npm can never be used again;
230
+ `npm publish --dry-run` shows the files it would ship, which is the check to make before the real one.
231
+ 2. On the package's npm settings page, under **Trusted Publisher** (or with `npm trust gitlab`), they choose **GitLab
232
+ CI/CD** and enter, with the case exactly as written: namespace `widgeticai/Frontend` (the full group path, subgroups
233
+ included), project name `workflows`, top-level CI file path `.gitlab-ci.yml`, and `npm publish` as an allowed action.
234
+ That last one matters: a configuration made after 3 September 2026 allows only `npm stage publish` until
235
+ `npm publish` is allowed, and the CI job runs `npm publish`. npm does not check the fields when they are saved, so a
236
+ wrong one shows up as `ENEEDAUTH` in the `publish` job.
237
+ 3. Within two days, the CI has to make a successful publish of its own, or npm drops the configuration (create it again
238
+ when the CI can run). A publish from a laptop is not this step, because it leaves the CI with nothing to publish:
239
+ raise `version`, commit and push `main` once the CI has minutes.
240
+ 4. From then on a push to `main` that raises the version publishes it.
241
+
242
+ ## License
243
+
244
+ Widgetic Integration License, version 1.0. See [LICENSE](./LICENSE).
@@ -0,0 +1,107 @@
1
+ <!--
2
+ The workflows screen: where a team builds the workflows that decide which composition an embed shows, and (later) how
3
+ visitors moved through them. This is the root. It is the one place that knows the page's language and reading
4
+ direction; every part of the screen below it asks for them.
5
+
6
+ V1 draws the shell only: the header and the "nothing yet" state. The editor and the runs arrive on top of this root
7
+ without changing what a page passes in.
8
+
9
+ Look and feel: nothing in here is a literal colour, font or corner. Everything reads the Widgetic palette
10
+ (`bg-white`, `text-ink-*`, `border-grey2`, `bg-primary-green`, `text-error`) and the `font-sans` / `rounded-*` scales,
11
+ which a page, or a ui-sdk theme, sets through CSS custom properties. Placement is logical (`ms-`, `me-`, `text-start`)
12
+ so the screen turns around for right to left languages.
13
+
14
+ Room: the screen fills the element it is in (`h-full w-full`). The element is the page's, and it may be shorter than
15
+ the screen needs, so the screen scrolls inside it (`overflow-auto`) and never spills over what the page has below.
16
+ -->
17
+ <script lang="ts">
18
+ import { untrack } from 'svelte';
19
+ import { writable } from 'svelte/store';
20
+ import {
21
+ shareTextDirection,
22
+ type TextDirection
23
+ } from '@widgetic/design-system/components/textDirection';
24
+ import { provideWorkflowsLanguage } from '../i18n/language.js';
25
+ import type { WorkflowsProps } from '../types/index.js';
26
+ import { workflowsError } from '../utils/logger.js';
27
+ import WorkflowsEmptyState from './WorkflowsEmptyState.svelte';
28
+ import WorkflowsHeader from './WorkflowsHeader.svelte';
29
+
30
+ let {
31
+ locale = null,
32
+ messages: languageMessages = null,
33
+ dir = undefined,
34
+ class: className = '',
35
+ onError
36
+ }: WorkflowsProps = $props();
37
+
38
+ // Why stores and effects below instead of `$derived`: the design system's language (`update()`) and direction
39
+ // (`shareTextDirection(given: Readable)`) contexts are store based, and every part below this root reads them as
40
+ // stores. The effects push the props into those stores; no `$state` is assigned here, so there is nothing for
41
+ // `$derived` to replace.
42
+
43
+ // "Language": made once from what the page gave, and set again below whenever the page changes it.
44
+ const language = provideWorkflowsLanguage(
45
+ untrack(() => ({ locale, messages: languageMessages }))
46
+ );
47
+ $effect(() => {
48
+ language.update({ locale, messages: languageMessages });
49
+ });
50
+ const { t } = language;
51
+
52
+ // "Reading Direction": handed down to every part through the shared store; `dir` left out means the surrounding screen's.
53
+ const givenDirection = writable<TextDirection | undefined>(untrack(() => dir));
54
+ const textDirection = shareTextDirection(givenDirection);
55
+ $effect(() => {
56
+ givenDirection.set(dir);
57
+ });
58
+
59
+ /**
60
+ * A part of the screen threw while it was being drawn. The screen shows its "Try again" in place of the part, and the
61
+ * page is told once. A handler of the page that throws must not take the screen down with it.
62
+ */
63
+ function reportRenderFailure(error: unknown): void {
64
+ const failureMessage = error instanceof Error ? error.message : String(error);
65
+ workflowsError(`The screen could not be drawn: ${failureMessage}`, error);
66
+ try {
67
+ onError?.({ message: failureMessage, code: 'RENDER_FAILED', fatal: false });
68
+ } catch (handlerError) {
69
+ workflowsError('The onError handler of the page threw.', handlerError);
70
+ }
71
+ }
72
+ </script>
73
+
74
+ <svelte:boundary onerror={reportRenderFailure}>
75
+ <section
76
+ class="flex h-full min-h-0 w-full flex-col gap-6 overflow-auto bg-white p-6 font-sans text-ink-primary {className}"
77
+ dir={$textDirection}
78
+ aria-label={$t('workflows.region.label')}
79
+ >
80
+ <WorkflowsHeader />
81
+ <WorkflowsEmptyState />
82
+ </section>
83
+
84
+ <!--
85
+ The failure itself is already reported to the console and to the page (reportRenderFailure); this only needs `reset`.
86
+ `justify-center-safe`: centred while it fits, and from the top when the page's element is too short, so that the
87
+ part above the edge can still be scrolled to (plain `justify-center` would cut it off).
88
+ -->
89
+ <!-- eslint-disable-next-line @typescript-eslint/no-unused-vars -->
90
+ {#snippet failed(_error, reset)}
91
+ <section
92
+ class="flex h-full min-h-0 w-full flex-col items-center justify-center-safe gap-3 overflow-auto bg-white p-6 text-center font-sans text-ink-primary {className}"
93
+ dir={$textDirection}
94
+ role="alert"
95
+ >
96
+ <h2 class="text-base font-medium text-error">{$t('workflows.error.title')}</h2>
97
+ <p class="max-w-md text-sm text-ink-muted">{$t('workflows.error.hint')}</p>
98
+ <button
99
+ type="button"
100
+ class="rounded-medium bg-primary-green px-4 py-2 text-sm font-medium text-white transition-opacity hover:opacity-90 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-green"
101
+ onclick={reset}
102
+ >
103
+ {$t('workflows.error.retry')}
104
+ </button>
105
+ </section>
106
+ {/snippet}
107
+ </svelte:boundary>
@@ -0,0 +1,4 @@
1
+ import type { WorkflowsProps } from '../types/index.js';
2
+ declare const Workflows: import("svelte").Component<WorkflowsProps, {}, "">;
3
+ type Workflows = ReturnType<typeof Workflows>;
4
+ export default Workflows;
@@ -0,0 +1,21 @@
1
+ <!--
2
+ What the screen shows while there is nothing to list: what a workflow is, and that building them is on its way. In V1
3
+ this is the whole body of the screen; once workflows can be made, the list takes this place and this becomes the
4
+ "first workflow" prompt.
5
+
6
+ No fill: the palette's `ink-muted` reads at 4.6 to 1 on white and at 4.2 to 1 on `grey1`, which is under WCAG's 4.5 for
7
+ text this size, so the hints sit on the screen's own white and the box is drawn with its dashed border alone.
8
+ -->
9
+ <script lang="ts">
10
+ import { useWorkflowsLanguage } from '../i18n/language.js';
11
+
12
+ const { t } = useWorkflowsLanguage();
13
+ </script>
14
+
15
+ <div
16
+ class="flex flex-1 flex-col items-center justify-center gap-2 rounded-large border border-dashed border-grey2 p-10 text-center"
17
+ >
18
+ <h2 class="text-base font-medium">{$t('workflows.empty.title')}</h2>
19
+ <p class="max-w-md text-sm text-ink-muted">{$t('workflows.empty.hint')}</p>
20
+ <p class="text-xs text-ink-muted">{$t('workflows.empty.comingSoon')}</p>
21
+ </div>
@@ -0,0 +1,18 @@
1
+ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
2
+ new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
3
+ $$bindings?: Bindings;
4
+ } & Exports;
5
+ (internal: unknown, props: {
6
+ $$events?: Events;
7
+ $$slots?: Slots;
8
+ }): Exports & {
9
+ $set?: any;
10
+ $on?: any;
11
+ };
12
+ z_$$bindings?: Bindings;
13
+ }
14
+ declare const WorkflowsEmptyState: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
15
+ [evt: string]: CustomEvent<any>;
16
+ }, {}, {}, string>;
17
+ type WorkflowsEmptyState = InstanceType<typeof WorkflowsEmptyState>;
18
+ export default WorkflowsEmptyState;
@@ -0,0 +1,14 @@
1
+ <!--
2
+ The top of the workflows screen: its title and the one line that says what a workflow does. Later the "New workflow"
3
+ action lands here, next to the title.
4
+ -->
5
+ <script lang="ts">
6
+ import { useWorkflowsLanguage } from '../i18n/language.js';
7
+
8
+ const { t } = useWorkflowsLanguage();
9
+ </script>
10
+
11
+ <header class="flex flex-col gap-1 text-start">
12
+ <h1 class="text-2xl font-semibold tracking-tight">{$t('workflows.header.title')}</h1>
13
+ <p class="text-sm text-ink-muted">{$t('workflows.header.subtitle')}</p>
14
+ </header>
@@ -0,0 +1,18 @@
1
+ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
2
+ new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
3
+ $$bindings?: Bindings;
4
+ } & Exports;
5
+ (internal: unknown, props: {
6
+ $$events?: Events;
7
+ $$slots?: Slots;
8
+ }): Exports & {
9
+ $set?: any;
10
+ $on?: any;
11
+ };
12
+ z_$$bindings?: Bindings;
13
+ }
14
+ declare const WorkflowsHeader: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
15
+ [evt: string]: CustomEvent<any>;
16
+ }, {}, {}, string>;
17
+ type WorkflowsHeader = InstanceType<typeof WorkflowsHeader>;
18
+ export default WorkflowsHeader;
@@ -0,0 +1,3 @@
1
+ export { default as Workflows } from './Workflows.svelte';
2
+ export { default as WorkflowsEmptyState } from './WorkflowsEmptyState.svelte';
3
+ export { default as WorkflowsHeader } from './WorkflowsHeader.svelte';
@@ -0,0 +1,3 @@
1
+ export { default as Workflows } from './Workflows.svelte';
2
+ export { default as WorkflowsEmptyState } from './WorkflowsEmptyState.svelte';
3
+ export { default as WorkflowsHeader } from './WorkflowsHeader.svelte';
@@ -0,0 +1,2 @@
1
+ export { WORKFLOWS_MESSAGES, type WorkflowsMessageKey } from './messages.js';
2
+ export { checkWorkflowsMessages, provideWorkflowsLanguage, useWorkflowsLanguage } from './language.js';
@@ -0,0 +1,2 @@
1
+ export { WORKFLOWS_MESSAGES } from './messages.js';
2
+ export { checkWorkflowsMessages, provideWorkflowsLanguage, useWorkflowsLanguage } from './language.js';
@@ -0,0 +1,22 @@
1
+ import { type MessageOverrides, type MessageProblem } from '@widgetic/design-system/i18n';
2
+ /**
3
+ * Called by the root component while it is created, so everything inside it speaks the page's language. It gives back the
4
+ * words as stores and `update(settings)` for when the page sets the language again.
5
+ */
6
+ export declare const provideWorkflowsLanguage: (initial: import("@widgetic/design-system/i18n").I18nSettings) => import("@widgetic/design-system/i18n").I18nHandle<"workflows.region.label" | "workflows.header.title" | "workflows.header.subtitle" | "workflows.empty.title" | "workflows.empty.hint" | "workflows.empty.comingSoon" | "workflows.error.title" | "workflows.error.hint" | "workflows.error.retry">;
7
+ /**
8
+ * Called by a part of the screen while it is created. Gives its words as stores, so a part that is already on the screen
9
+ * changes when the page sets the language again. Outside a `Workflows` (a part used on its own) it speaks English.
10
+ */
11
+ export declare const useWorkflowsLanguage: () => import("@widgetic/design-system/i18n").I18nContext<"workflows.region.label" | "workflows.header.title" | "workflows.header.subtitle" | "workflows.empty.title" | "workflows.empty.hint" | "workflows.empty.comingSoon" | "workflows.error.title" | "workflows.error.hint" | "workflows.error.retry">;
12
+ /**
13
+ * The English `t` of the screen, for code that has no component around it. The parts of the screen get their words, in the
14
+ * page's language, from `useWorkflowsLanguage`.
15
+ */
16
+ export declare const translateEnglish: import("@widgetic/design-system/i18n").Translate<"workflows.region.label" | "workflows.header.title" | "workflows.header.subtitle" | "workflows.empty.title" | "workflows.empty.hint" | "workflows.empty.comingSoon" | "workflows.error.title" | "workflows.error.hint" | "workflows.error.retry">;
17
+ /**
18
+ * Checks a page's `messages` against the catalog without showing anything: a key that does not exist (with the nearest real
19
+ * one), a value that is not text, a template that does not parse, or one that asks for a value the message is never given.
20
+ * An empty list means every message will be used. For a test or a build step of the page.
21
+ */
22
+ export declare function checkWorkflowsMessages(messages: MessageOverrides): MessageProblem[];
@@ -0,0 +1,34 @@
1
+ import { createI18n, findMessageProblems } from '@widgetic/design-system/i18n';
2
+ import { WORKFLOWS_MESSAGES } from './messages.js';
3
+ /**
4
+ * The language of a workflows screen on a page. `Workflows` is the root: it takes `locale` and `messages`, makes the
5
+ * language here, and every part of the screen below it reads its words from it (`useWorkflowsLanguage`). The context
6
+ * belongs to one root, so two screens on a page can speak two languages.
7
+ */
8
+ const workflowsWords = createI18n({
9
+ catalog: WORKFLOWS_MESSAGES,
10
+ label: 'Workflows'
11
+ });
12
+ /**
13
+ * Called by the root component while it is created, so everything inside it speaks the page's language. It gives back the
14
+ * words as stores and `update(settings)` for when the page sets the language again.
15
+ */
16
+ export const provideWorkflowsLanguage = workflowsWords.provideI18n;
17
+ /**
18
+ * Called by a part of the screen while it is created. Gives its words as stores, so a part that is already on the screen
19
+ * changes when the page sets the language again. Outside a `Workflows` (a part used on its own) it speaks English.
20
+ */
21
+ export const useWorkflowsLanguage = workflowsWords.useI18n;
22
+ /**
23
+ * The English `t` of the screen, for code that has no component around it. The parts of the screen get their words, in the
24
+ * page's language, from `useWorkflowsLanguage`.
25
+ */
26
+ export const translateEnglish = workflowsWords.translateEnglish;
27
+ /**
28
+ * Checks a page's `messages` against the catalog without showing anything: a key that does not exist (with the nearest real
29
+ * one), a value that is not text, a template that does not parse, or one that asks for a value the message is never given.
30
+ * An empty list means every message will be used. For a test or a build step of the page.
31
+ */
32
+ export function checkWorkflowsMessages(messages) {
33
+ return findMessageProblems(WORKFLOWS_MESSAGES, messages);
34
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Every word the workflows screen shows to the person using it, in English: the one place to read them, and the keys a
3
+ * page can replace with the `messages` of `Workflows`.
4
+ *
5
+ * A message is plain text. `{name}` is a value the screen puts in; `{count, plural, one {# step} other {# steps}}` picks the
6
+ * form that fits a number in the page's language. `\{`, `\}`, `\#` and `\\` write those characters themselves. See
7
+ * `@widgetic/design-system/i18n` for the whole format.
8
+ *
9
+ * Keys are grouped by where the words appear (`workflows.<where>.<what>`). A key that is left out of a page's `messages`
10
+ * keeps the English text below, so a language can be added a screen at a time.
11
+ *
12
+ * Words that are NOT here, on purpose:
13
+ * - what a person wrote: the name of a workflow, of a step and of a filter are shown as they were written, in the
14
+ * language they were written in.
15
+ * - the lines the server reports (a failed request, a refused plan): they are shown as they arrive.
16
+ */
17
+ export declare const WORKFLOWS_MESSAGES: {
18
+ /** The name of the region a workflows screen is, for a person who uses a screen reader. */
19
+ 'workflows.region.label': string;
20
+ 'workflows.header.title': string;
21
+ /** One line under the title: what a workflow does. */
22
+ 'workflows.header.subtitle': string;
23
+ 'workflows.empty.title': string;
24
+ 'workflows.empty.hint': string;
25
+ 'workflows.empty.comingSoon': string;
26
+ 'workflows.error.title': string;
27
+ 'workflows.error.hint': string;
28
+ 'workflows.error.retry': string;
29
+ };
30
+ /** The key of a message of the workflows screen. */
31
+ export type WorkflowsMessageKey = keyof typeof WORKFLOWS_MESSAGES;
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Every word the workflows screen shows to the person using it, in English: the one place to read them, and the keys a
3
+ * page can replace with the `messages` of `Workflows`.
4
+ *
5
+ * A message is plain text. `{name}` is a value the screen puts in; `{count, plural, one {# step} other {# steps}}` picks the
6
+ * form that fits a number in the page's language. `\{`, `\}`, `\#` and `\\` write those characters themselves. See
7
+ * `@widgetic/design-system/i18n` for the whole format.
8
+ *
9
+ * Keys are grouped by where the words appear (`workflows.<where>.<what>`). A key that is left out of a page's `messages`
10
+ * keeps the English text below, so a language can be added a screen at a time.
11
+ *
12
+ * Words that are NOT here, on purpose:
13
+ * - what a person wrote: the name of a workflow, of a step and of a filter are shown as they were written, in the
14
+ * language they were written in.
15
+ * - the lines the server reports (a failed request, a refused plan): they are shown as they arrive.
16
+ */
17
+ export const WORKFLOWS_MESSAGES = {
18
+ // ===== The screen as a whole =====
19
+ /** The name of the region a workflows screen is, for a person who uses a screen reader. */
20
+ 'workflows.region.label': 'Workflows',
21
+ // ===== The header =====
22
+ 'workflows.header.title': 'Workflows',
23
+ /** One line under the title: what a workflow does. */
24
+ 'workflows.header.subtitle': 'Decide which composition your embed shows, step by step.',
25
+ // ===== Nothing made yet =====
26
+ 'workflows.empty.title': 'No workflows yet',
27
+ 'workflows.empty.hint': 'A workflow chains compositions together. Filters between them decide which one a visitor sees next.',
28
+ 'workflows.empty.comingSoon': 'Workflows are on their way. You will be able to build them here.',
29
+ // ===== When a part of the screen fails to draw =====
30
+ 'workflows.error.title': 'Workflows could not be shown',
31
+ 'workflows.error.hint': 'Something went wrong while this screen was being drawn.',
32
+ 'workflows.error.retry': 'Try again'
33
+ };
@@ -0,0 +1,3 @@
1
+ export { Workflows, WorkflowsEmptyState, WorkflowsHeader } from './components/index.js';
2
+ export { WORKFLOWS_MESSAGES, checkWorkflowsMessages, provideWorkflowsLanguage, useWorkflowsLanguage, type WorkflowsMessageKey } from './i18n/index.js';
3
+ export type { WorkflowsError, WorkflowsErrorCode, WorkflowsProps } from './types/index.js';
package/dist/index.js ADDED
@@ -0,0 +1,5 @@
1
+ // Reexport your entry components here
2
+ // The screen. Everything a page needs to show workflows is this one component.
3
+ export { Workflows, WorkflowsEmptyState, WorkflowsHeader } from './components/index.js';
4
+ // The words of the screen, and the check a page runs on its own translations.
5
+ export { WORKFLOWS_MESSAGES, checkWorkflowsMessages, provideWorkflowsLanguage, useWorkflowsLanguage } from './i18n/index.js';
@@ -0,0 +1,38 @@
1
+ import type { TextDirection } from '@widgetic/design-system/i18n';
2
+ /** Why `onError` was called. */
3
+ export type WorkflowsErrorCode =
4
+ /** A part of the screen threw while it was being drawn. The screen shows "Try again" in its place. */
5
+ 'RENDER_FAILED';
6
+ /**
7
+ * What `onError` is told when something goes wrong. The screen shows the problem to the person using it by itself; this is
8
+ * for the page around it. The `message` is English, for the page's developer: it is not a sentence to show a visitor.
9
+ */
10
+ export interface WorkflowsError {
11
+ message: string;
12
+ code: WorkflowsErrorCode;
13
+ /** `true` when the screen cannot go on. A part that failed to draw is not fatal: the person can try again. */
14
+ fatal: boolean;
15
+ }
16
+ /** What the `Workflows` component takes. All of it is optional: a bare `<Workflows />` is a screen in English. */
17
+ export interface WorkflowsProps {
18
+ /**
19
+ * A BCP 47 language tag (`de`, `pt-BR`, `ar-EG`): the plural rules and how numbers and dates are written. It translates
20
+ * nothing by itself (see `messages`). Blank or left out is English.
21
+ */
22
+ locale?: string | null;
23
+ /**
24
+ * The page's own words: any message of `WORKFLOWS_MESSAGES` by key. A key that is left out stays English, so a language
25
+ * can be added a screen at a time. `checkWorkflowsMessages` finds a mistake before a visitor does.
26
+ */
27
+ messages?: Readonly<Record<string, unknown>> | null;
28
+ /**
29
+ * Which way the screen is read. `'rtl'` lays it out from the right. It is NOT worked out from `locale`: the page
30
+ * decides it (`resolveTextDirection(locale)` from `@widgetic/design-system/i18n` answers it for a language tag). Left
31
+ * out, the screen is drawn the way the screen around it is.
32
+ */
33
+ dir?: TextDirection;
34
+ /** Extra classes for the root element, for the page that gives the screen its size. */
35
+ class?: string;
36
+ /** Called when something goes wrong, once for each failure. See {@link WorkflowsError}. */
37
+ onError?: (error: WorkflowsError) => void;
38
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,4 @@
1
+ /** Says something that is not a failure but that the page's developer should know, once. */
2
+ export declare function workflowsWarn(message: string, detail?: unknown): void;
3
+ /** Says a failure, once. */
4
+ export declare function workflowsError(message: string, detail?: unknown): void;
@@ -0,0 +1,35 @@
1
+ /**
2
+ * The console of the package. Every line starts with `[Workflows]`, and a line that was already said is not said again:
3
+ * a screen that fails every time it is drawn must not fill a page's console.
4
+ */
5
+ const LOG_PREFIX = '[Workflows]';
6
+ /** How many different lines are remembered, so a page that keeps failing in new ways cannot fill memory. */
7
+ const MAX_REMEMBERED_LINES = 100;
8
+ const saidLines = new Set();
9
+ /** Whether this line was already said. Remembers it when it was not. */
10
+ function wasSaidBefore(line) {
11
+ if (saidLines.has(line))
12
+ return true;
13
+ if (saidLines.size >= MAX_REMEMBERED_LINES)
14
+ saidLines.clear();
15
+ saidLines.add(line);
16
+ return false;
17
+ }
18
+ /** Says something that is not a failure but that the page's developer should know, once. */
19
+ export function workflowsWarn(message, detail) {
20
+ if (wasSaidBefore(`warn:${message}`))
21
+ return;
22
+ if (detail === undefined)
23
+ console.warn(`${LOG_PREFIX} ${message}`);
24
+ else
25
+ console.warn(`${LOG_PREFIX} ${message}`, detail);
26
+ }
27
+ /** Says a failure, once. */
28
+ export function workflowsError(message, detail) {
29
+ if (wasSaidBefore(`error:${message}`))
30
+ return;
31
+ if (detail === undefined)
32
+ console.error(`${LOG_PREFIX} ${message}`);
33
+ else
34
+ console.error(`${LOG_PREFIX} ${message}`, detail);
35
+ }
package/package.json CHANGED
@@ -1,6 +1,100 @@
1
1
  {
2
- "name": "@widgetic/workflows",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@widgetic/workflows",
3
+ "version": "0.1.1",
4
+ "description": "Workflows for Widgetic: chain compositions together with filters that decide which composition an embed shows. One Svelte package that the Widgetic site, partners and Shopify all load.",
5
+ "license": "SEE LICENSE IN LICENSE",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "svelte": "./dist/index.js",
10
+ "sideEffects": [
11
+ "**/*.css"
12
+ ],
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "svelte": "./dist/index.js",
17
+ "default": "./dist/index.js"
18
+ },
19
+ "./components": {
20
+ "types": "./dist/components/index.d.ts",
21
+ "svelte": "./dist/components/index.js",
22
+ "default": "./dist/components/index.js"
23
+ },
24
+ "./i18n": {
25
+ "types": "./dist/i18n/index.d.ts",
26
+ "svelte": "./dist/i18n/index.js",
27
+ "default": "./dist/i18n/index.js"
28
+ },
29
+ "./types": {
30
+ "types": "./dist/types/index.d.ts",
31
+ "default": "./dist/types/index.js"
32
+ }
33
+ },
34
+ "files": [
35
+ "dist"
36
+ ],
37
+ "scripts": {
38
+ "i": "npm run clean-modules && npm i",
39
+ "clean-modules": "rm -rf node_modules",
40
+ "dev": "npm run dev-sv -- --open",
41
+ "dev-sv": "NODE_ENV=development vite dev",
42
+ "build": "vite build",
43
+ "package": "svelte-kit sync && svelte-package",
44
+ "prepublishOnly": "npm run package",
45
+ "publish-to-npm": "node ../dev-tools/bin/publish-package.mjs",
46
+ "package:watch": "svelte-kit sync && svelte-package --watch",
47
+ "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --diagnostic-sources \"js,svelte\"",
48
+ "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
49
+ "test": "node --test \"tests/**/*.test.mjs\"",
50
+ "lint": "prettier --check . && eslint .",
51
+ "format": "prettier --write ."
52
+ },
53
+ "peerDependencies": {
54
+ "@widgetic/design-system": ">=0.5.21",
55
+ "svelte": "^5.25.6"
56
+ },
57
+ "devDependencies": {
58
+ "@eslint/js": "^9.0.0",
59
+ "@sveltejs/adapter-auto": "^3.0.0",
60
+ "@sveltejs/kit": "^2.20.3",
61
+ "@sveltejs/package": "^2.3.7",
62
+ "@sveltejs/vite-plugin-svelte": "^5.0.3",
63
+ "@tailwindcss/postcss": "^4.1.4",
64
+ "@types/node": "^26.4.1",
65
+ "@widgetic/design-system": "^0.5.21",
66
+ "@widgetic/dev-tools": "^0.3.7",
67
+ "eslint": "^9.0.0",
68
+ "eslint-config-prettier": "^9.1.0",
69
+ "eslint-plugin-svelte": "^3.0.0",
70
+ "globals": "^15.0.0",
71
+ "postcss": "^8.5.3",
72
+ "prettier": "^3.1.1",
73
+ "prettier-plugin-svelte": "^3.1.2",
74
+ "svelte": "^5.25.6",
75
+ "svelte-check": "^4.0.0",
76
+ "tailwindcss": "^4.1.4",
77
+ "typescript": "^5.8.3",
78
+ "typescript-eslint": "^8.0.0",
79
+ "vite": "^6.2.6"
80
+ },
81
+ "overrides": {
82
+ "tar": "^7.5.22",
83
+ "bits-ui": {
84
+ "@melt-ui/svelte": "^0.86.3"
85
+ },
86
+ "vaul-svelte": {
87
+ "bits-ui": {
88
+ "@melt-ui/svelte": "^0.86.3"
89
+ }
90
+ },
91
+ "svelte": "^5.25.6"
92
+ },
93
+ "publishConfig": {
94
+ "access": "public"
95
+ },
96
+ "repository": {
97
+ "type": "git",
98
+ "url": "https://gitlab.com/widgeticai/Frontend/workflows.git"
99
+ }
100
+ }