diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml index bb8a1624..30cade8c 100755 --- a/.github/workflows/desktop.yml +++ b/.github/workflows/desktop.yml @@ -106,6 +106,10 @@ jobs: # main CAD file (Check out and open after Cancel, #348) - name: Test the Get rules run: node scripts/desktop-get-rules.test.mjs + # the steps of the first-start wizard *Getting started* (#422): which + # are skipped, when it shows by itself, the texts + - name: Test the first-start wizard rules + run: node scripts/desktop-onboarding-rules.test.mjs # the empty states name the next step, by role (#423) - name: Test the empty state rules run: node scripts/desktop-empty-rules.test.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index d62b3e2c..14b841f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,20 @@ see the notices in the README. ### Added +- **Getting started in the desktop app** (#422): after the first sign-in + TeamCraft Desktop opens a short wizard – server (skipped when a policy fixes + it), sign-in, the working folder (*Change…*, *Open folder*), *Get project + groups…* for your groups (latest revision, also in work; skipped without + groups or when they are already fetched), the CAD setup for information + (the Inventor `.ipj`, NX load options and Solid Edge search paths a later + version will create – nothing is created now) and the daily loop *Check out + and open* → save in CAD → *Check in…*, ending in *Finish and open* with + one of your groups: its files open in Home, ready for *Check out and open* + on the assembly. Every step but the last can be skipped; *Finish* + or *Don't show again* is kept in the settings (`onboarding`), and *Help → + Getting Started…* opens it again. The wizard creates no file or folder by + itself. Step rules in `desktop/ui/js/onboarding-rules.js`, tested by + `scripts/desktop-onboarding-rules.test.mjs`. - **Check out several parts of an assembly at once** (#415): `POST /api/v1/checkouts` takes a list of revisions (by id, or item and code) and checks them out in one transaction with a result per revision – the ones that can be taken are checked diff --git a/README.md b/README.md index a1e5cd48..98fc03f4 100755 --- a/README.md +++ b/README.md @@ -313,7 +313,8 @@ end-to-end tests against a real PostgreSQL. *Settings → Language*. Empty lists name the next step, by role – viewers learn why they see no editing buttons (#423). - **Desktop app** – Linux, macOS and Windows client with a local working - folder, *Get* of whole assemblies, an import wizard, a *Files* view of each + folder, a *Getting started* wizard after the first sign-in (working folder, + *Get* of your project groups, the daily loop), *Get* of whole assemblies, an import wizard, a *Files* view of each project group (with *New item here* on every folder, starting in a favourite folder, e.g. the one with the Inventor project file, if you like), a navigable *Graph* of every revision (BOM children, references and where-used, coloured by state, with quantities and preview diff --git a/desktop/README.md b/desktop/README.md index 2e186695..f2ac669b 100755 --- a/desktop/README.md +++ b/desktop/README.md @@ -20,6 +20,7 @@ TeamCraft server – it is a client, not an offline copy. | Area | What the desktop app does | |---|---| | Sign-in | **Sign in with the browser** (single sign-on or password, confirmed on a TeamCraft page) or a personal access token; *cancel* stops the sign-in at once | +| Getting started | A short wizard after the **first sign-in** and from *Help → Getting Started…* (#422): server (skipped when a policy fixes it), sign-in (done), **working folder** (what it is, the path, *Change…* with the folder picker, *Open folder*), **project group** (the groups you are a member of, *Get project groups…* – latest revision, also in work; skipped without groups or when a complete Get on this computer – no failed item or name clash, *Latest revision* – already fetched them into this working folder), **CAD setup** (for information only: the Inventor `.ipj`, NX load options and Solid Edge search paths a later version will offer – nothing is created) and **your daily loop** (*Check out and open* → save in CAD → *Check in…*; *Finish and open* + group code makes that group active and shows its files in Home, a fetched group first – *Finish and show Projects* only without a group). Every step has *Don't show again*; *Back*, *Skip* and *Next* move between the steps, the last step has *Finish*; the step list marks skipped steps with a dash and done ones with a tick, also as hidden text for screen readers; the wizard creates no file or folder itself, only through the app's own confirmed actions. *Finish* or *Don't show again* is stored as `onboarding` in `settings.json`; an app that starts already signed in (an update from an older version) does not show it by itself. Step rules in `ui/js/onboarding-rules.js`, tested by `scripts/desktop-onboarding-rules.test.mjs` (`node`); the dialog in `ui/js/onboarding.js` | | Connections | Several servers and several accounts on one server (#322, #323): *Settings → Connections* lists the saved ones (server, account, working folder) with *Switch* and *Remove*; *Add another account…* signs in a second account on the same server, *Switch server…* (and the connect screen) changes the server **without signing out**. The sign-in of the connection left behind is parked in the keychain (`api-token@`, or a private `token-` file without one) and comes back when you switch to it; the window reloads. Every connection after the first has its **own working folder** next to the default one (`TeamCraft-`, numbered for a second account), never inside another, so files of servers with the same item numbers never mix; the first keeps its folder. At most 20 connections; removing one keeps its folder on disk (`src/profiles.rs`) A sign-in kept from an app version before the connections gets its account noted the first time the server confirms it (`GET /me`, #356) | | Local test server | Downloads *with local server* only – an app of its own, *TeamCraft Local* (own identifier, settings and keychain entry): on its first start, with no server configured, and with *Try TeamCraft on this computer* on the connect screen it starts the bundled `teamcraft-server local` (private PostgreSQL + server on 127.0.0.1), signs in through the browser (the first start creates the administrator there) and starts the server again at every launch while it is the configured server; it stops when the app ends (`src/localserver.rs`, log in `local-server.log`) | | Navigator | *Home*: a file browser of the **active project group** – *Files*: its folders and the files in them, as in the working folder (folders first, then the files by name – case-blind, digits by value; one folder per request from `GET /projects/{code}/files`, 500 entries at a time with *show … more*; items without files below the files of their own folder; **+** on a folder row = *New item here*; a checked-out row is marked with a bar in the lock colour and a light tint, also in *Structure* – #362; with an older server the items instead; a folder's ☆ makes it the group's **favourite folder**: Home starts there under a banner in the accent colour – *not the top of the group*, *Whole group*, *Remove favourite* – and the folder of the group's Inventor project file `.ipj` (`project_folders`) is suggested; kept per computer, server and group, #352), *All items*: every item in one list, or the *Structure* view. The name comes first (the number/revision dimmed after it); a small picture of the model replaces the type icon in *Files*, *All items*, *Structure* and the search (named by the list answers, fetched only for rows in view through an `IntersectionObserver`, kept per content hash – `js/list-thumbs.js`, #420); sorted by name, number, type or state (kept per computer); *Projects* (`Ctrl/Cmd+5`): choose the active group (mine first), create a group (*New*, CAD editors), *Get…* groups into the workspace, *Import CAD folder…*. Both are loaded again on *Refresh* (a group created in the web UI shows without a restart); *My Worklist* (check-outs, reviews, my open changes – updated at once after a check-out, cancelled check-out, check-in or acknowledgement in a tab, #347); change orders by status; full-text search | diff --git a/desktop/src/commands.rs b/desktop/src/commands.rs index 145d0447..1544bf02 100755 --- a/desktop/src/commands.rs +++ b/desktop/src/commands.rs @@ -120,6 +120,8 @@ pub struct Session { /// Managed deployment policies (#378): the organisation and the settings /// fixed by a policy. pub policy: policy::PolicyView, + /// The first-start wizard: `done`, `dismissed` or none (#422). + pub onboarding: Option, } #[tauri::command] @@ -141,6 +143,7 @@ pub fn session(app: AppHandle, state: State<'_, AppState>) -> Session { local_server_available: localserver::sidecar().is_some(), local_server_in_use: local_server_in_use(&s), policy: policy::current().view(), + onboarding: s.onboarding.clone(), } } @@ -1087,6 +1090,16 @@ pub fn dismiss_update(state: State<'_, AppState>, version: String) -> CmdResult< Ok(()) } +/// *Getting started* (#422): the wizard was finished (`done`) or closed with +/// *Don't show again* (`dismissed`); it then no longer opens by itself. +#[tauri::command] +pub fn set_onboarding(state: State<'_, AppState>, value: String) -> CmdResult<()> { + let value = crate::settings::onboarding_value(&value) + .ok_or_else(|| ApiError::local(format!("'{value}' is not a state of the wizard.")))?; + update_settings(&state, |s| s.onboarding = Some(value.to_string()))?; + Ok(()) +} + /// *Remind me later*: no notice for three days (#377). #[tauri::command] pub fn update_remind_later(state: State<'_, AppState>) -> CmdResult<()> { diff --git a/desktop/src/main.rs b/desktop/src/main.rs index ebd6d79b..a8d76052 100755 --- a/desktop/src/main.rs +++ b/desktop/src/main.rs @@ -155,6 +155,7 @@ fn build_menu(app: &tauri::App) -> tauri::Result<()> { .item(&item("open-web", "Open in Browser", None)?) .build()?; let help = SubmenuBuilder::new(app, "Help") + .item(&item("getting-started", "Getting Started…", None)?) .item(&item("import-help", "How to Import a CAD Folder", None)?) .item(&item("report-problem", "Report a Problem…", None)?) .item(&item("check-updates", "Check for Updates…", None)?) @@ -290,6 +291,7 @@ fn main() { commands::set_report_url, commands::check_update, commands::dismiss_update, + commands::set_onboarding, commands::update_remind_later, commands::check_update_now, commands::update_offer, diff --git a/desktop/src/settings.rs b/desktop/src/settings.rs index 29635aca..07deb369 100755 --- a/desktop/src/settings.rs +++ b/desktop/src/settings.rs @@ -223,6 +223,12 @@ pub struct Settings { /// Id of the active connection in [`Settings::profiles`]. #[serde(default)] pub active_profile: Option, + /// The first-start wizard *Getting started* (#422, ui/js/onboarding.js): + /// `"done"` or `"dismissed"` – it then no longer opens by itself (*Help → + /// Getting started…* still does). `None` in settings files of older + /// versions. + #[serde(default)] + pub onboarding: Option, /// Not stored in settings.json. #[serde(skip)] pub token: Option, @@ -282,6 +288,15 @@ pub(crate) fn write_private_file(dir: &Path, name: &str, content: &str) -> anyho Ok(()) } +/// The values of [`Settings::onboarding`]; anything else is refused. +pub fn onboarding_value(value: &str) -> Option<&'static str> { + match value { + "done" => Some("done"), + "dismissed" => Some("dismissed"), + _ => None, + } +} + /// Most remembered Agent view backends (servers × users). pub const MAX_AGENT_BACKENDS: usize = 32; @@ -757,4 +772,43 @@ mod tests { .unwrap(); assert!(s.save_token_with(dir.path(), &keychain, None).is_err()); } + + /// A settings file of an older version has no `onboarding`: it still + /// loads, with the wizard not done (#422). + #[test] + fn settings_without_onboarding_still_load() { + let dir = tempfile::tempdir().unwrap(); + fs::write( + dir.path().join(SETTINGS_FILE), + r#"{"server_url":"https://plm.example.org","skin":"teamcraft"}"#, + ) + .unwrap(); + let loaded = Settings::load_with(dir.path(), &FakeKeychain::new(true)); + assert_eq!( + loaded.server_url.as_deref(), + Some("https://plm.example.org") + ); + assert_eq!(loaded.onboarding, None); + } + + #[test] + fn onboarding_is_saved_and_loaded() { + let dir = tempfile::tempdir().unwrap(); + let s = Settings { + onboarding: Some("dismissed".into()), + ..Settings::default() + }; + s.save(dir.path()).unwrap(); + let loaded = Settings::load_with(dir.path(), &FakeKeychain::new(true)); + assert_eq!(loaded.onboarding.as_deref(), Some("dismissed")); + } + + #[test] + fn only_done_and_dismissed_are_onboarding_values() { + assert_eq!(onboarding_value("done"), Some("done")); + assert_eq!(onboarding_value("dismissed"), Some("dismissed")); + for bad in ["", "Done", "later", "done ", "dismissed\n"] { + assert_eq!(onboarding_value(bad), None, "{bad:?}"); + } + } } diff --git a/desktop/ui/app.css b/desktop/ui/app.css index 77b2ca81..6a062914 100755 --- a/desktop/ui/app.css +++ b/desktop/ui/app.css @@ -23,6 +23,8 @@ html, body { margin: 0; padding: 0; height: 100%; overflow: hidden; } body { background: var(--bg); color: var(--text); } .hidden { display: none !important; } +/* read by screen readers, not shown (e.g. the step status of Getting started) */ +.visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; } /* Distro skins paint their glow and texture here, behind the page; the house skins set both to none. Nothing else reads --glow or --pattern. */ @@ -900,6 +902,28 @@ canvas.viewer-measuring { cursor: crosshair; } .dialog-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 20px; flex-wrap: wrap; } .dialog .error-text { color: var(--st-danger-fg); margin: 8px 0 0; } +/* Getting started (#422, js/onboarding.js): the steps on the left, the + current one on the right; narrow windows stack them. */ +.onboarding { display: grid; grid-template-columns: 180px minmax(0, 1fr); gap: 20px; } +.onboarding-steps { margin: 0; padding: 0; list-style: none; display: grid; gap: 4px; align-content: start; counter-reset: onboarding; } +.onboarding-steps li { + counter-increment: onboarding; + display: grid; gap: 2px; padding: 6px 8px 6px 28px; position: relative; + border-radius: var(--radius); color: var(--text-dim); +} +.onboarding-steps li::before { content: counter(onboarding); position: absolute; left: 8px; top: 6px; font-variant-numeric: tabular-nums; } +.onboarding-steps li.current { color: var(--text); background: var(--accent-soft); box-shadow: inset 3px 0 0 var(--accent); font-weight: 600; } +.onboarding-steps li.done { color: var(--text); } +.onboarding-steps li.done::before { content: "\2713"; color: var(--st-ok-fg); } +.onboarding-steps li.skipped::before { content: "\2013"; } +.onboarding-body h3 { margin: 0; } +.onboarding-body p { margin: 0; } +.onboarding-path { display: block; padding: 6px 8px; background: var(--surface-2); border: 1px solid var(--border); border-radius: var(--radius); overflow-wrap: anywhere; } +.onboarding-cad { margin: 0; padding-left: 18px; display: grid; gap: 6px; } +@media (max-width: 640px) { + .onboarding { grid-template-columns: minmax(0, 1fr); } +} + /* Appearance: the three house cards (System, Light, Dark) first and larger, the distribution skins after them. Each card renders its own tokens. */ .skin-grid { display: grid; gap: 8px; grid-template-columns: repeat(12, minmax(0, 1fr)); } diff --git a/desktop/ui/js/core.js b/desktop/ui/js/core.js index a29d1d4a..ac929de5 100755 --- a/desktop/ui/js/core.js +++ b/desktop/ui/js/core.js @@ -49,7 +49,8 @@ export var state = { viewer: null, zoom: 1, update: null, // the newer release the status bar tells about: {version, current} - tokenFileWarned: false // the "no keychain" warning shows once per start + tokenFileWarned: false, // the "no keychain" warning shows once per start + signedInAtStart: null // the app started signed in (false: the user signs in now – the first-start wizard, onboarding.js) }; // ====================================================================== diff --git a/desktop/ui/js/group-sync.js b/desktop/ui/js/group-sync.js index f6f302a3..296d1c1c 100755 --- a/desktop/ui/js/group-sync.js +++ b/desktop/ui/js/group-sync.js @@ -20,6 +20,31 @@ export function projectItems(code) { return page(0); } +/** Key of the groups fetched with *Get project groups* into this working + * folder (per folder: each connection has its own). */ +function gotGroupsKey() { + return "teamcraft.got-groups:" + String(state.session && state.session.workspace_dir || ""); +} + +/** Codes of the project groups a finished *Get project groups* copied into + * the current working folder on this computer – the first-start wizard + * (onboarding.js) skips its group step for them. Only a convenience: an + * empty answer (private window, cleared storage) just shows the step. */ +export function gotGroups() { + try { + var list = JSON.parse(window.localStorage.getItem(gotGroupsKey()) || "[]"); + return Array.isArray(list) ? list.filter(function (c) { return typeof c === "string"; }) : []; + } catch (e) { return []; } +} + +/** Remembers the groups of a Get that ran to its end without a problem + * (not stopped, no failed item or name clash, rule *Latest revision*). */ +export function rememberGotGroups(list) { + var all = gotGroups(); + (list || []).forEach(function (c) { if (all.indexOf(c) === -1) all.push(c); }); + try { window.localStorage.setItem(gotGroupsKey(), JSON.stringify(all.slice(-200))); } catch (e) { /* storage blocked: the step shows again */ } +} + /** For new team members or a fresh computer: copies the files of every item * of the chosen project groups into the workspace, one folder per group. * `opts.project` (a group code) ticks only that group – the *Get…* of an @@ -87,6 +112,8 @@ export function openGetProjectsDialog(opts) { }, Promise.resolve()); }).then(function () { running = false; + // only a complete copy: no problems, no clashes, the latest revision of every item + if (!stop && !done.errors.length && rule.value === "latest") rememberGotGroups(codes); var text = (stop ? "Stopped. " : "Done. ") + done.items + " items, " + done.files + " files copied" + (done.kept ? ", " + done.kept + " locally modified files kept" : "") + (done.skipped ? ", " + done.skipped + " items without a released revision skipped" : "") + diff --git a/desktop/ui/js/main.js b/desktop/ui/js/main.js index 2f26ba1c..7b695e79 100755 --- a/desktop/ui/js/main.js +++ b/desktop/ui/js/main.js @@ -9,7 +9,7 @@ // Every server call goes through the Rust commands (src/commands.rs); data // from the server is only ever inserted as text, never as HTML. // -// Modules: core.js, skins.js, connect.js, shell.js, navigator.js, tabs.js, assistant.js, agent.js, revision.js, references.js, workspace.js, change.js, requests.js, dialogs.js, bom-import.js, bom-lines.js, group-sync.js, folder-import.js, settings.js, crash.js, main.js. +// Modules: core.js, skins.js, connect.js, shell.js, navigator.js, tabs.js, assistant.js, agent.js, revision.js, references.js, workspace.js, change.js, requests.js, dialogs.js, bom-import.js, bom-lines.js, group-sync.js, folder-import.js, settings.js, onboarding-rules.js, onboarding.js, crash.js, main.js. import { $, TAURI, call, errorText, h, invoke, setStatus, state, toast } from "./core.js"; import { applySkin } from "./skins.js"; @@ -29,6 +29,7 @@ import { reportDialog } from "./report.js"; import { checkCrashReports, initCrashWatch } from "./crash.js"; import { onSolidcraftRequest } from "./solidcraft-bridge.js"; import { initItemMenu } from "./item-menu.js"; +import { openOnboarding } from "./onboarding.js"; // ====================================================================== // Zoom: Ctrl + mouse wheel (trackpads: pinch), Ctrl/Cmd + + / - / 0 @@ -101,6 +102,7 @@ export function handleMenu(id) { case "import-folder": importFolderDialog(); break; case "import-bom": importBomDialog(null); break; case "import-help": importTutorial(); break; + case "getting-started": openOnboarding(true); break; case "settings": case "settings-app": openSettings(); break; case "sign-out": signOut(); break; case "refresh": selectView(state.view); reloadActive(); refreshWorklistCount(); break; @@ -157,6 +159,8 @@ export function boot() { var languageReady = loadLanguage(preferredLanguage()).catch(function () {}); languageReady.then(function () { return call("session"); }).then(function (s) { state.session = s; + // signed in already: no first-start wizard (onboarding.js) + state.signedInAtStart = !!s.signed_in; showAppVersion(s.version); state.zoom = s.zoom || 1; showZoom(); diff --git a/desktop/ui/js/onboarding-rules.js b/desktop/ui/js/onboarding-rules.js new file mode 100644 index 00000000..4a956035 --- /dev/null +++ b/desktop/ui/js/onboarding-rules.js @@ -0,0 +1,186 @@ +// SPDX-License-Identifier: MPL-2.0 +// TeamCraft Desktop – pure rules of the first-start wizard (*Getting +// started*, #422): which steps there are, which are skipped, when the wizard +// shows and the texts of each step. +// No imports and no DOM: scripts/desktop-onboarding-rules.test.mjs tests it +// with plain Node.js. Used by onboarding.js. + +/** The steps in order. */ +export var ONBOARDING_STEPS = ["server", "signin", "folder", "group", "cad", "loop"]; + +/** The values the app stores in settings.json (`onboarding`, src/settings.rs). */ +export var ONBOARDING_DONE = "done", ONBOARDING_DISMISSED = "dismissed"; + +/** + * Whether the wizard opens by itself. `settings.onboarding` is the stored + * value (`"done"`, `"dismissed"` or none); `ctx.fromHelp` is *Help → Getting + * started…*, which always opens it; `ctx.signedInThisRun` is true when the + * user came through the connect screen in this run of the app – a first start. + * An app that starts already signed in (an update of an older version, a + * reload of the window) does not show it: those users know the app. + */ +export function shouldShow(settings, ctx) { + ctx = ctx || {}; + if (ctx.fromHelp) return true; + var stored = settings && settings.onboarding; + if (stored === ONBOARDING_DONE || stored === ONBOARDING_DISMISSED) return false; + return !!ctx.signedInThisRun; +} + +/** Lower-case codes of a list of group codes (empty and non-text ones dropped). */ +function codes(list) { + return (Array.isArray(list) ? list : []).filter(function (c) { + return typeof c === "string" && c.trim() !== ""; + }).map(function (c) { return c.trim().toLowerCase(); }); +} + +/** + * Why a step is skipped, or null when it is shown. `facts`: + * + * * `serverFixed` – an organisation policy sets the server (#378); + * * `signedIn` – the app has a sign-in; + * * `groups` – codes of the project groups the user is a member of; + * * `groupsOnDisk` – codes of the groups already fetched into this working folder. + */ +export function skipReason(step, facts) { + facts = facts || {}; + switch (step) { + case "server": + return facts.serverFixed ? "Set by your organization" : null; + case "signin": + return facts.signedIn ? "Signed in" : null; + case "group": { + var mine = codes(facts.groups); + if (!mine.length) return "You are not a member of a project group yet"; + var onDisk = codes(facts.groupsOnDisk); + if (mine.every(function (c) { return onDisk.indexOf(c) !== -1; })) return "Your project groups are already in the working folder"; + return null; + } + default: + return ONBOARDING_STEPS.indexOf(step) === -1 ? "Unknown step" : null; + } +} + +/** The steps that are shown, in order. */ +export function visibleSteps(facts) { + return ONBOARDING_STEPS.filter(function (s) { return skipReason(s, facts) === null; }); +} + +/** + * The step after `current` that is shown, or null when the wizard is at its + * end. `current` null (or unknown) starts at the first shown step. + * `wizard.back` goes the other way: the shown step before `current`, null + * at the start. + */ +export function nextStep(wizard, facts) { + wizard = wizard || {}; + var shown = visibleSteps(facts); + var at = shown.indexOf(wizard.current); + if (wizard.back) return at > 0 ? shown[at - 1] : null; + if (at === -1) { + // a step that is skipped now (the group was fetched meanwhile): go on + // with the first shown step after it in the full order + var full = ONBOARDING_STEPS.indexOf(wizard.current); + if (full === -1) return shown[0] || null; + for (var i = full + 1; i < ONBOARDING_STEPS.length; i++) { + if (shown.indexOf(ONBOARDING_STEPS[i]) !== -1) return ONBOARDING_STEPS[i]; + } + return null; + } + return at + 1 < shown.length ? shown[at + 1] : null; +} + +/** + * The project group the last step opens in Home (*Finish and open *): + * the first of the user's groups that a Get already fetched into this working + * folder, else the first of the user's groups; null without groups (the step + * then offers the Projects page). Returns the code as given in `facts.groups`. + */ +export function startGroup(facts) { + facts = facts || {}; + var mine = (Array.isArray(facts.groups) ? facts.groups : []).filter(function (c) { + return typeof c === "string" && c.trim() !== ""; + }); + if (!mine.length) return null; + var onDisk = codes(facts.groupsOnDisk); + var fetched = mine.filter(function (c) { return onDisk.indexOf(c.trim().toLowerCase()) !== -1; }); + return (fetched[0] || mine[0]).trim(); +} + +/** `Step 2 of 4` of a shown step; "" for one that is skipped. */ +export function stepPosition(step, facts) { + var shown = visibleSteps(facts); + var at = shown.indexOf(step); + return at === -1 ? "" : "Step " + (at + 1) + " of " + shown.length; +} + +/** + * What the planned CAD setup would create (OPEN_WORK §4, *Workspace setup + * wizard*). Shown for information only: the wizard writes none of it yet. + */ +export var CAD_SETUP_PREVIEW = [ + { program: "Inventor", file: "//.ipj", what: "a project file whose workspace is the group's folder, so references resolve inside the working folder" }, + { program: "NX", file: "load_options.def", what: "load options that search the group's folder (and its subfolders) for components" }, + { program: "Solid Edge", file: "search paths", what: "the group's folder as a search path for linked documents" } +]; + +/** Short names of the steps (the list on the left of the wizard). */ +export var STEP_NAMES = { + server: "Server", + signin: "Sign-in", + folder: "Working folder", + group: "Project group", + cad: "CAD setup", + loop: "Daily loop" +}; + +/** + * Title and paragraphs of a step. `facts` as for skipReason, plus + * `serverUrl`, `workspaceDir`, `username`, `groups`. + */ +export function stepSummary(step, facts) { + facts = facts || {}; + var ws = facts.workspaceDir || "the default folder"; + var mine = codes(facts.groups); + switch (step) { + case "server": + return { title: "Your TeamCraft server", text: [ + facts.serverUrl ? "TeamCraft Desktop works with the server at " + facts.serverUrl + "." : "TeamCraft Desktop needs the address of your TeamCraft server.", + facts.serverFixed ? "Your organization set this server; it cannot be changed here." : "You can switch to another server later in Settings → Account." + ] }; + case "signin": + return { title: "Sign in", text: [ + facts.signedIn ? "You are signed in" + (facts.username ? " as " + facts.username : "") + "." : "Sign in with your TeamCraft account or your organization's single sign-on.", + "The sign-in is kept in your system's keychain, so you do not have to sign in at every start." + ] }; + case "folder": + return { title: "Your working folder", text: [ + "Your CAD files live in the working folder on this computer: " + ws + ".", + "Every project group gets its own folder in it, with the folders of its files: ///. Open and save your CAD files there.", + "Files you have not checked out are read-only; checking out makes them writable, checking in sends your changes to the server." + ] }; + case "group": + return { title: "Get your project group", text: [ + mine.length ? "You are a member of " + (mine.length === 1 ? "the project group " : mine.length + " project groups: ") + facts.groups.filter(function (c) { return typeof c === "string" && c.trim(); }).join(", ") + "." : "You are not a member of a project group yet.", + "Get project groups… copies the files of every item of a group into your working folder – the latest revision, also the ones still in work – so assemblies open with all their parts.", + "Nothing is overwritten: files you changed locally are kept and name clashes are reported." + ] }; + case "cad": + return { title: "CAD setup", text: [ + "Some CAD programs find the parts of an assembly through a project file or search paths. Point them at your working folder.", + "A later version of TeamCraft Desktop will offer to create these files for you – nothing ticked by default and never overwriting yours. Nothing is created now." + ] }; + case "loop": { + var start = startGroup(facts); + return { title: "Your daily loop in 3 steps", text: [ + "1. Check out and open – on an item or in its Workspace tab: locks the item for you, copies its files (and the parts of an assembly) and opens the main file in your CAD program.", + "2. Save in your CAD program – into the working folder, as always.", + "3. Check in… – sends the changed files to the server with a comment and releases the lock. Your worklist shows what you have checked out.", + start ? "Start now: Finish and open " + start + " shows the files of the group in Home – right-click the assembly → Check out and open." + : "Start now: Finish and show Projects lists the project groups – choose one, then right-click an assembly in its files → Check out and open." + ] }; + } + default: + return { title: "", text: [] }; + } +} diff --git a/desktop/ui/js/onboarding.js b/desktop/ui/js/onboarding.js new file mode 100644 index 00000000..4b2853c6 --- /dev/null +++ b/desktop/ui/js/onboarding.js @@ -0,0 +1,172 @@ +// SPDX-License-Identifier: MPL-2.0 +// TeamCraft Desktop – the first-start wizard *Getting started* (#422): from +// the sign-in to the working folder, the project group and the daily loop +// (Check out and open → save in CAD → Check in…). +// Part of the desktop UI (ES modules, no build step; js/main.js starts it). +// +// The steps, which are skipped and their texts are pure rules in +// onboarding-rules.js. The wizard itself creates no file and no folder: it +// only opens the app's own confirmed actions (the folder picker, *Get project +// groups*), and stores `done` or `dismissed` in the settings. + +import { $, TAURI, call, dialog, errorText, h, state, toast } from "./core.js"; +import { CAD_SETUP_PREVIEW, ONBOARDING_DISMISSED, ONBOARDING_DONE, ONBOARDING_STEPS, STEP_NAMES, nextStep, shouldShow, skipReason, startGroup, stepPosition, stepSummary } from "./onboarding-rules.js"; +import { fixedByPolicy } from "./settings.js"; +import { getProjectsDialog, gotGroups } from "./group-sync.js"; +import { selectView, setActiveProject } from "./navigator.js"; +import { openWorkspaceFolder } from "./workspace.js"; + +/** The open wizard's dialog (one at a time). */ +var wizardDialog = null; + +/** Steps the user passed with *Skip* in this run of the wizard (the step + * list marks them skipped, not done). */ +var skippedSteps = new Set(); + +/** What the step rules need to know, read from the session now. */ +function onboardingFacts() { + var me = state.me || {}; + var memberOf = Array.isArray(me.projects) ? me.projects : []; + var groups = state.projects.filter(function (p) { + return p.active && memberOf.indexOf(p.id) !== -1; + }).map(function (p) { return p.code; }); + return { + serverFixed: fixedByPolicy("server"), + serverUrl: state.session && state.session.server_url, + signedIn: !!(state.session && state.session.signed_in) || !!state.me, + username: me.display_name || me.username || "", + workspaceDir: state.session && state.session.workspace_dir, + groups: groups, + groupsOnDisk: gotGroups() + }; +} + +/** Stores `done` or `dismissed` (src/settings.rs `onboarding`). */ +function saveOnboarding(value) { + return call("set_onboarding", { value: value }).then(function () { + if (state.session) state.session.onboarding = value; + }, function (err) { toast(errorText(err), "error", "Getting started"); }); +} + +/** After the shell opened: the wizard on the first start (shouldShow). */ +export function maybeStartOnboarding() { + var ctx = { signedInThisRun: state.signedInAtStart === false }; + if (!shouldShow(state.session || {}, ctx)) return; + openOnboarding(false); +} + +/** Opens the wizard; `fromHelp` is *Help → Getting started…*, which always opens it. */ +export function openOnboarding(fromHelp) { + if (!shouldShow(state.session || {}, { fromHelp: !!fromHelp, signedInThisRun: state.signedInAtStart === false })) return; + if (wizardDialog) return; + skippedSteps = new Set(); + showStep(nextStep({ current: null }, onboardingFacts())); +} + +function closeWizard() { + if (wizardDialog) wizardDialog.close(); + wizardDialog = null; +} + +/** The list of all steps on the left: done, current, skipped (with why). + * The status is also spoken (a visually hidden text), not only the CSS + * tick or dash. */ +function stepList(current, facts) { + var passed = true; + return h("ol.onboarding-steps", { "aria-label": "Steps" }, ONBOARDING_STEPS.map(function (s) { + if (s === current) passed = false; + var why = skipReason(s, facts); + // the sign-in is skipped because it is done: a tick, not a dash; + // a step passed with *Skip* is skipped, not done + var status = s === current ? "current" : s === "signin" && why ? "done" : why ? "skipped" + : passed && skippedSteps.has(s) ? "skipped" : passed ? "done" : ""; + return h("li" + (status ? "." + status : ""), { title: why || null, "aria-current": s === current ? "step" : null }, [ + h("span", { text: STEP_NAMES[s] }), + status === "done" || status === "skipped" ? h("span.visually-hidden", { text: " (" + status + ")" }) : null, + why ? h("span.small.muted", { text: why }) : null + ]); + })); +} + +/** The extra controls of a step (they only open the app's own actions). */ +function stepExtras(step, facts) { + switch (step) { + case "folder": + return h("div.stack", null, [ + h("code.onboarding-path", { text: facts.workspaceDir || "" }), + h("div.row", null, [ + TAURI.dialog ? h("button", { type: "button", on: { click: function () { changeFolder(facts.workspaceDir); } } }, "Change…") : null, + h("button", { type: "button", on: { click: function () { openWorkspaceFolder(null); } } }, "Open folder") + ]) + ]); + case "group": + return h("div.row", null, [ + h("button", { type: "button", on: { click: function () { getProjectsDialog(); } } }, "Get project groups…") + ]); + case "cad": + return h("ul.onboarding-cad", null, CAD_SETUP_PREVIEW.map(function (p) { + return h("li", null, [ + h("strong", { text: p.program }), ": ", + h("code", { text: p.file }), " – " + p.what + " ", + h("span.small.muted", { text: "(not created)" }) + ]); + })); + case "loop": { + // finish here and go where the loop starts: the files of the group in + // Home (as choosing it on the Projects page does), or the group picker + // for a user without groups + var start = startGroup(facts); + return h("div.row", null, [ + start + ? h("button", { type: "button", on: { click: function () { showStep(null); setActiveProject(start); selectView("home"); } } }, "Finish and open " + start) + : h("button", { type: "button", on: { click: function () { showStep(null); selectView("projects"); } } }, "Finish and show Projects"), + h("button", { type: "button", on: { click: function () { showStep(null); selectView("worklist"); } } }, "Finish and open my worklist") + ]); + } + default: + return null; + } +} + +/** *Change…*: the folder picker, then the same command as Settings → Workspace. */ +function changeFolder(current) { + TAURI.dialog.open({ directory: true, defaultPath: current || undefined }).then(function (dir) { + if (!dir) return null; + return call("set_workspace_dir", { dir: dir }).then(function () { + state.session.workspace_dir = dir; + var status = $("status-ws"); + if (status) status.textContent = "Workspace: " + dir; + if (wizardDialog && wizardDialog.step === "folder") showStep("folder"); + }); + }).catch(function (err) { toast(errorText(err), "error", "Change working folder"); }); +} + +/** Shows `step`; null finishes the wizard (`done`). */ +function showStep(step) { + closeWizard(); + if (!step) { saveOnboarding(ONBOARDING_DONE); return; } + var facts = onboardingFacts(); + var sum = stepSummary(step, facts); + var back = nextStep({ current: step, back: true }, facts); + var last = !nextStep({ current: step }, facts); + var body = h("div.onboarding", null, [ + stepList(step, facts), + h("div.onboarding-body.stack", null, [ + h("p.hint", { text: stepPosition(step, facts) }), + h("h3", { text: sum.title }), + sum.text.map(function (para) { return h("p", { text: para }); }), + stepExtras(step, facts) + ]) + ]); + function go() { showStep(nextStep({ current: step }, onboardingFacts())); } + function skip() { skippedSteps.add(step); go(); } + function next() { skippedSteps.delete(step); go(); } + var actions = [ + { label: "Don't show again", onClick: function () { closeWizard(); saveOnboarding(ONBOARDING_DISMISSED); } }, + back ? { label: "Back", onClick: function () { showStep(back); } } : null, + last ? null : { label: "Skip", onClick: skip }, + { label: last ? "Finish" : "Next", primary: true, submit: true, onClick: next } + ].filter(Boolean); + wizardDialog = dialog("Getting started", body, actions, { wide: true, modal: true }); + wizardDialog.step = step; +} diff --git a/desktop/ui/js/shell.js b/desktop/ui/js/shell.js index 11bc2cbc..fdf8f3d5 100755 --- a/desktop/ui/js/shell.js +++ b/desktop/ui/js/shell.js @@ -16,6 +16,7 @@ import { openRequest } from "./requests.js"; import { openSettings } from "./settings.js"; import { formatKinds } from "./folder-import.js"; import { planNewFiles } from "./new-files.js"; +import { maybeStartOnboarding } from "./onboarding.js"; // ====================================================================== // Shell @@ -133,6 +134,8 @@ export function enterShell() { checkWorkspaceLayout(); checkTokenStorage(); checkUpdate(); + // the first start after the sign-in: *Getting started* (#422) + maybeStartOnboarding(); }).catch(function (err) { if (!(err && err.status === 401)) showConnect("signin", errorText(err)); }); diff --git a/docs/OPEN_WORK.md b/docs/OPEN_WORK.md index b7c2acbc..06834f4a 100755 --- a/docs/OPEN_WORK.md +++ b/docs/OPEN_WORK.md @@ -686,7 +686,10 @@ real files and belong to section 3 once such files are at hand. instead of importing them again and again - [ ] Workspace setup wizard (first start or when getting a project group): optional CAD settings to tick – Inventor `.ipj`, NX load options, Solid Edge search paths; nothing ticked by default, preview of what would be created, never - created automatically, existing files never overwritten without asking; can be opened again from the settings + created automatically, existing files never overwritten without asking; can be opened again from the settings. + The wizard frame exists (#422: *Getting started* in the desktop app, also *Help → Getting Started…*); its *CAD + setup* step only lists what would be created. Left: creating the files themselves (needs the CAD programs to + verify the generated `.ipj`, load options and search paths); issue #422 stays open for this step 5 of its plan **Autodesk Inventor** @@ -881,7 +884,8 @@ needs an issue with a reason first (see *Direction*). - [ ] Upgrades: proven upgrade chain per release, restore-based rollback guide, a plugin/extension layer (design: research page *A sandboxed extension layer*, #382) - [ ] CAD clone workflows: clone an assembly with selective reuse, Save As / revise per component over a whole structure, shown as an indented tree -- [ ] Interactive onboarding and contextual help +- [ ] Interactive onboarding and contextual help – the desktop first-start wizard *Getting started* is done (#422); + left: empty states that name the next step (#423) and contextual help - [ ] Migration tooling from commercial PLM/PDM systems - [ ] GA proofs: production readiness, migration and concurrency safety, scale validation, external security review, support and versioning policy diff --git a/docs/src/guide/desktop.md b/docs/src/guide/desktop.md index 5e8accdf..3c490131 100755 --- a/docs/src/guide/desktop.md +++ b/docs/src/guide/desktop.md @@ -693,6 +693,45 @@ whose newer revision takes the place, stay where they are; files you changed are moved first. Identical copies are removed, emptied old folders too, and every step is written to `.teamcraft/migration.log`. +## Getting started + +After the **first sign-in** the app opens a short wizard, *Getting +started*; *Help → Getting Started…* opens it again at any time. It guides +you from the sign-in to your first opened assembly: + +1. **Server** – the server the app works with. Skipped when your + organization fixed the server ([Managed computers](#managed-computers)). +2. **Sign-in** – already done when the wizard opens; shown as a ticked step. +3. **Working folder** – what it is and where your CAD files will live + (`///`). *Change…* picks another + folder (the same setting as *Settings → Workspace*), *Open folder* shows + it in the file manager. +4. **Project group** – the groups you are a member of and *Get project + groups…*, which copies their files into the working folder (latest + revision, also in work). Skipped when you are in no group yet, or when a + complete *Get project groups* on this computer (no failed item or name + clash, *Latest revision*) already fetched all of + them into this working folder. +5. **CAD setup** – for information only: the Inventor project file + (`.ipj`), the NX load options and the Solid Edge search paths that a later + version will offer to create. The wizard creates none of them. +6. **Your daily loop in 3 steps** – *Check out and open* → save in your CAD + program → *Check in…*. *Finish and open* with the group code makes one of your + groups the active one (a group you already fetched first) and shows its + files in *Home* – right-click the assembly → *Check out and open*. Without + a group, *Finish and show Projects* lists the groups instead; *Finish and + open my worklist* shows what you have checked out. + +Every step has *Don't show again*; *Back*, *Skip* and *Next* move between +the steps, and the last step has *Finish*. The step list on the left ticks +the steps you went through with *Next* and marks the ones you skipped with +a dash (also read out by screen readers). The wizard +itself creates no file or folder – only the app's own actions it opens do, +after you confirm them (the folder picker, *Get files*). Once you finish it +or choose *Don't show again* it no longer opens by itself; an app that +starts already signed in – after an update from an older version – does not +show it either. + ## Empty views An empty list says what to do next, and the answer depends on your role diff --git a/docs/src/guide/getting-started.md b/docs/src/guide/getting-started.md index c564506c..33aba42b 100755 --- a/docs/src/guide/getting-started.md +++ b/docs/src/guide/getting-started.md @@ -66,6 +66,13 @@ installations and the desktop app: files; its first revision *A* is *in work* and checked out to you. 5. **Check in**, then release it with a change order. +**Desktop app, first start:** after you connect to the server and sign in, +TeamCraft Desktop opens *Getting started* – a short wizard through the +working folder, *Get project groups…* for your groups, the CAD setup (for +information) and the daily loop *Check out and open* → save in CAD → +*Check in…*. Every step can be skipped; *Help → Getting Started…* opens it +again. See [Desktop app](desktop.md#getting-started). + **Empty pages name the next step** (#423): with no project group yet, the vault and *Projects* offer *Create a project group* to CAD editors and tell viewers to ask a manager of a group to add them; an empty project group in diff --git a/scripts/desktop-onboarding-rules.test.mjs b/scripts/desktop-onboarding-rules.test.mjs new file mode 100644 index 00000000..f6a0b32c --- /dev/null +++ b/scripts/desktop-onboarding-rules.test.mjs @@ -0,0 +1,185 @@ +// SPDX-License-Identifier: MPL-2.0 +// Unit tests of desktop/ui/js/onboarding-rules.js (the steps of the +// first-start wizard *Getting started* – #422). +// Plain Node.js, no packages; run by the CI job `ui`: +// +// node scripts/desktop-onboarding-rules.test.mjs +// +// The module sits in a folder without package.json, so it is imported as a +// data: URL module instead of by path. +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const file = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../desktop/ui/js/onboarding-rules.js"); +const src = fs.readFileSync(file, "utf8"); +const { + ONBOARDING_STEPS, ONBOARDING_DONE, ONBOARDING_DISMISSED, CAD_SETUP_PREVIEW, STEP_NAMES, + shouldShow, skipReason, visibleSteps, nextStep, stepPosition, stepSummary, startGroup +} = await import("data:text/javascript;base64," + Buffer.from(src).toString("base64")); + +let n = 0; +function test(name, fn) { fn(); n++; console.log("ok - " + name); } + +// a user right after the first sign-in: server not fixed, one group not on disk yet +const fresh = { serverFixed: false, signedIn: true, groups: ["ROVER"], groupsOnDisk: [], serverUrl: "https://plm.example.org", workspaceDir: "/home/u/TeamCraft" }; + +test("the steps and their order", () => { + assert.deepEqual(ONBOARDING_STEPS, ["server", "signin", "folder", "group", "cad", "loop"]); + for (const s of ONBOARDING_STEPS) assert.ok(STEP_NAMES[s], "a name for " + s); +}); + +test("the stored values match the Rust side", () => { + assert.equal(ONBOARDING_DONE, "done"); + assert.equal(ONBOARDING_DISMISSED, "dismissed"); +}); + +test("shown on the first start after the sign-in", () => { + assert.equal(shouldShow({}, { signedInThisRun: true }), true); + assert.equal(shouldShow({ onboarding: null }, { signedInThisRun: true }), true); +}); + +test("never shown again once done or dismissed", () => { + assert.equal(shouldShow({ onboarding: "done" }, { signedInThisRun: true }), false); + assert.equal(shouldShow({ onboarding: "dismissed" }, { signedInThisRun: true }), false); +}); + +test("not shown when the app starts signed in (an update, a reload)", () => { + assert.equal(shouldShow({}, { signedInThisRun: false }), false); + assert.equal(shouldShow({}, {}), false); + assert.equal(shouldShow(null, undefined), false); +}); + +test("Help → Getting started always opens it", () => { + assert.equal(shouldShow({ onboarding: "done" }, { fromHelp: true }), true); + assert.equal(shouldShow({ onboarding: "dismissed" }, { fromHelp: true }), true); + assert.equal(shouldShow(null, { fromHelp: true }), true); +}); + +test("an unknown stored value counts as not done", () => { + assert.equal(shouldShow({ onboarding: "later" }, { signedInThisRun: true }), true); +}); + +test("a server fixed by policy skips the server step (#378)", () => { + assert.equal(skipReason("server", { ...fresh, serverFixed: true }), "Set by your organization"); + assert.equal(skipReason("server", fresh), null); + assert.ok(!visibleSteps({ ...fresh, serverFixed: true }).includes("server")); +}); + +test("a sign-in skips the sign-in step", () => { + assert.equal(skipReason("signin", fresh), "Signed in"); + assert.equal(skipReason("signin", { ...fresh, signedIn: false }), null); +}); + +test("no groups skips the group step", () => { + assert.match(skipReason("group", { ...fresh, groups: [] }), /not a member/); + assert.match(skipReason("group", { ...fresh, groups: undefined }), /not a member/); + assert.match(skipReason("group", { ...fresh, groups: ["", null, 7] }), /not a member/); +}); + +test("groups already on disk skip the group step, ignoring case", () => { + assert.match(skipReason("group", { ...fresh, groupsOnDisk: ["rover"] }), /already/); + assert.equal(skipReason("group", { ...fresh, groups: ["ROVER", "SAT"], groupsOnDisk: ["ROVER"] }), null); +}); + +test("folder, CAD setup and the daily loop are always shown", () => { + for (const s of ["folder", "cad", "loop"]) assert.equal(skipReason(s, {}), null); +}); + +test("an unknown step is skipped", () => { + assert.equal(skipReason("nope", fresh), "Unknown step"); +}); + +test("visible steps of a fresh user", () => { + assert.deepEqual(visibleSteps(fresh), ["server", "folder", "group", "cad", "loop"]); + assert.deepEqual(visibleSteps({ ...fresh, serverFixed: true, groups: [] }), ["folder", "cad", "loop"]); + assert.deepEqual(visibleSteps({}), ["server", "signin", "folder", "cad", "loop"]); +}); + +test("next step walks the shown steps and ends with null", () => { + const order = []; + let s = nextStep({ current: null }, fresh); + while (s) { order.push(s); s = nextStep({ current: s }, fresh); } + assert.deepEqual(order, visibleSteps(fresh)); +}); + +test("next step skips the server when it is fixed", () => { + assert.equal(nextStep({}, { ...fresh, serverFixed: true }), "folder"); + assert.equal(nextStep(undefined, { ...fresh, serverFixed: true }), "folder"); +}); + +test("back goes to the shown step before, null at the start", () => { + assert.equal(nextStep({ current: "cad", back: true }, fresh), "group"); + assert.equal(nextStep({ current: "cad", back: true }, { ...fresh, groups: [] }), "folder"); + assert.equal(nextStep({ current: "server", back: true }, fresh), null); +}); + +test("a step skipped meanwhile goes on after it (the group was fetched)", () => { + const got = { ...fresh, groupsOnDisk: ["ROVER"] }; + assert.equal(nextStep({ current: "group" }, got), "cad"); + assert.equal(nextStep({ current: "loop" }, got), null); +}); + +test("an unknown current step starts at the beginning", () => { + assert.equal(nextStep({ current: "nope" }, fresh), "server"); +}); + +test("step positions count shown steps only", () => { + assert.equal(stepPosition("server", fresh), "Step 1 of 5"); + assert.equal(stepPosition("loop", fresh), "Step 5 of 5"); + assert.equal(stepPosition("signin", fresh), ""); +}); + +test("every step has a title and text", () => { + for (const s of ONBOARDING_STEPS) { + const sum = stepSummary(s, fresh); + assert.ok(sum.title, "title of " + s); + assert.ok(sum.text.length > 0, "text of " + s); + } + assert.deepEqual(stepSummary("nope", fresh), { title: "", text: [] }); +}); + +test("the folder step names the working folder", () => { + assert.match(stepSummary("folder", fresh).text.join(" "), /\/home\/u\/TeamCraft/); + assert.match(stepSummary("folder", {}).text.join(" "), /the default folder/); +}); + +test("the group step names the groups", () => { + assert.match(stepSummary("group", fresh).text[0], /project group ROVER/); + assert.match(stepSummary("group", { groups: ["A", "B"] }).text[0], /2 project groups: A, B/); + assert.match(stepSummary("group", {}).text[0], /not a member/); +}); + +test("the server step says when the organization set it", () => { + assert.match(stepSummary("server", { ...fresh, serverFixed: true }).text.join(" "), /organization set this server/); + assert.match(stepSummary("server", fresh).text.join(" "), /Settings/); +}); + +test("the CAD step promises nothing is created now", () => { + assert.match(stepSummary("cad", fresh).text.join(" "), /Nothing is created now/); + assert.ok(CAD_SETUP_PREVIEW.length >= 3); + for (const p of CAD_SETUP_PREVIEW) assert.ok(p.program && p.file && p.what); +}); + +test("the loop step has the three steps", () => { + const text = stepSummary("loop", fresh).text; + assert.equal(text.length, 4); + assert.match(text[0], /Check out and open/); + assert.match(text[2], /Check in…/); + // the next action: open the group, then Check out and open on the assembly + assert.match(text[3], /Finish and open ROVER/); + assert.match(text[3], /Check out and open/); + assert.match(stepSummary("loop", { ...fresh, groups: [] }).text[3], /Finish and show Projects/); +}); + +test("the group the last step opens: a fetched one first, none without groups", () => { + assert.equal(startGroup(fresh), "ROVER"); + assert.equal(startGroup({ groups: ["ROVER", "ARM"], groupsOnDisk: ["arm"] }), "ARM"); + assert.equal(startGroup({ groups: ["ROVER", "ARM"], groupsOnDisk: [] }), "ROVER"); + assert.equal(startGroup({ groups: [], groupsOnDisk: ["arm"] }), null); + assert.equal(startGroup({ groups: ["", 3] }), null); + assert.equal(startGroup({}), null); +}); + +console.log(`${n} tests passed`);