@scalio-cloud/ui 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.24.0
+Einrichtungsassistent als Standard für alle Apps (scalio-docs ADR 0060, contract `interfaces/setup-wizard.md`).
+- New `SetupWizard`: the first-step dialog of Nexus and Kontor as a shared shell. Steps come as configuration
+  (`id`, `label`, `title`, `description`, `content`, `onNext`, `canNext`, `optional`); stepper on top, «Schritt n von
+  m», Zurück/Weiter, «Überspringen» for optional steps, errors of `onNext` keep the step open, short success message
+  at the end. Without `onClose` it cannot be closed; `wide` for steps with tables. Texts DE/EN in `labels.wizard`.
+- `setupWizardApi(api, {base})` for `GET/PUT /api/setup/wizard` (reads snake_case and camelCase), `useSetupWizard()`
+  (loads the state, opens once by itself at the saved step while the setup is needed, saves each step, completes),
+  `openSetupWizard()` and `SetupWizardButton` for Einstellungen.
+- Styles `.scalio-wizard*` in nav.css. No token changes, nothing changes until an app uses the wizard.
+
 ## 0.23.0
 Benutzerverwaltung in allen Apps angleichen (scalio-docs ADR 0059, `users/B1`–`B6`, contract `interfaces/app-users.md`).
 - New `UserAdmin` for Konten und Rollen → Benutzer, the same in every app: list with search and badges (Microsoft,

package/README.md

@@ -236,6 +236,34 @@ const users = usersApi(api);   // once, outside the component
 <MicrosoftConnection linked={user.microsoft} canUnlink={user.has_password} onLink={...} onUnlink={...} lang={lang} />
 ```
 
+## Setup wizard (React)
+
+Einrichtungsassistent after the first sign-in, the same in every app (ADR 0060, UISPEC section 3). The app writes
+only its steps; the backend follows scalio-docs `interfaces/setup-wizard.md` (`GET/PUT /api/setup/wizard`).
+
+```jsx
+import { SetupWizard, SetupWizardButton, useSetupWizard, setupWizardApi } from "@scalio-cloud/ui/react";
+
+const wizardClient = setupWizardApi(api);   // once, outside the component ({ base: "/wizard" } for another route)
+
+function AppWizard() {
+  const w = useSetupWizard({ client: wizardClient, enabled: isAdmin });   // opens by itself while needed
+  const steps = [
+    { id: "tenant", label: t("Tenant"), title: t("Connect Microsoft"), description: "...", content: <TenantsSection />,
+      canNext: connected, onNext: async () => { /* save; a rejected promise keeps the step open */ } },
+    { id: "mail", label: t("Email"), title: t("Email (SMTP)"), content: <SmtpForm />, optional: true },
+  ];
+  return <SetupWizard {...w.props} lang={lang} title={t("Set up Foundry")} subtitle={t("...")} steps={steps}
+    success={{ title: t("Setup complete"), text: t("...") }} />;
+}
+
+// Einstellungen: open it again (admins only)
+<SetupWizardButton lang={lang} />
+```
+
+Test IDs: `setup-wizard`, `wizard-stepper(-item)`, `wizard-step-{id}`, `wizard-next`, `wizard-back`, `wizard-skip`,
+`wizard-close`, `wizard-error`, `wizard-success`, `wizard-done`, `settings-open-wizard`.
+
 ## Two-factor card and license panel (React)
 
 The same backend routes in every app, so the apps pass only their axios instance and a few helpers.

package/nav.css

@@ -464,6 +464,41 @@
 .scalio-dialog-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 0.5rem; }
 .scalio-dialog-left { margin-right: auto; }
 
+/* Setup wizard (SetupWizard, ADR 0060): design of the Nexus wizard, first built in Kontor */
+.scalio-wizard-root { position: fixed; inset: 0; z-index: 60; display: flex; align-items: center; justify-content: center; padding: 1rem; background: rgb(0 0 0 / 0.5); }
+.scalio-wizard {
+  display: flex; flex-direction: column; gap: 1rem; width: calc(100vw - 2rem); max-width: 42rem; max-height: 90vh; overflow-y: auto;
+  padding: 1.5rem; border: 1px solid hsl(var(--border)); border-radius: 2px; background: hsl(var(--background)); color: hsl(var(--foreground));
+  box-shadow: 0 16px 40px rgb(0 0 0 / 0.25); font-size: 0.875rem;
+}
+.scalio-wizard.is-wide { max-width: 56rem; }
+.scalio-wizard-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 1rem; }
+.scalio-wizard-title { margin: 0; font-family: 'Chivo', sans-serif; font-size: 1.5rem; font-weight: 900; line-height: 1.2; text-transform: uppercase; letter-spacing: -0.025em; }
+.scalio-wizard-subtitle { margin: 0.25rem 0 0; color: hsl(var(--muted-foreground)); }
+.scalio-wizard-stepper { display: flex; align-items: center; gap: 0.5rem; margin: 0; padding: 0; list-style: none; }
+.scalio-wizard-stepper-item { display: flex; flex: 1 1 0; min-width: 0; align-items: center; gap: 0.5rem; }
+.scalio-wizard-dot {
+  display: flex; flex-shrink: 0; align-items: center; justify-content: center; width: 1.75rem; height: 1.75rem; border-radius: 999px;
+  background: hsl(var(--muted)); color: hsl(var(--muted-foreground)); font-size: 0.75rem; font-weight: 700;
+}
+.scalio-wizard-dot.is-current { background: hsl(var(--primary)); color: hsl(var(--primary-foreground)); }
+.scalio-wizard-dot.is-done, .scalio-wizard-success-icon { background: #059669; color: #fff; }
+.scalio-wizard-label { display: none; white-space: nowrap; font-size: 0.75rem; font-weight: 500; color: hsl(var(--muted-foreground)); }
+.scalio-wizard-label.is-current { color: hsl(var(--foreground)); }
+@media (min-width: 1024px) { .scalio-wizard-label { display: block; } }
+.scalio-wizard-line { flex: 1 1 0; min-width: 0.5rem; height: 1px; background: hsl(var(--border)); }
+.scalio-wizard-count { margin: 0; font-size: 0.75rem; font-weight: 500; color: hsl(var(--muted-foreground)); }
+.scalio-wizard-step { display: flex; flex-direction: column; gap: 0.75rem; }
+.scalio-wizard-step-title { margin: 0; font-size: 0.875rem; font-weight: 700; }
+.scalio-wizard-text { margin: 0; color: hsl(var(--muted-foreground)); }
+.scalio-wizard-actions { display: flex; align-items: center; justify-content: space-between; gap: 0.5rem; margin-top: 0.5rem; }
+.scalio-wizard-actions-right { display: flex; align-items: center; gap: 0.5rem; }
+.scalio-wizard-success { display: flex; flex-direction: column; align-items: center; gap: 0.75rem; padding: 1.5rem 0; text-align: center; }
+.scalio-wizard-success .scalio-wizard-step-title { font-size: 1.125rem; }
+.scalio-wizard-success .scalio-wizard-text { max-width: 28rem; }
+.scalio-wizard-success .scalio-btn { margin-top: 0.5rem; }
+.scalio-wizard-success-icon { display: flex; align-items: center; justify-content: center; width: 3rem; height: 3rem; border-radius: 999px; }
+
 /* License panel (LicensePanel) */
 .scalio-license { border: 1px solid hsl(var(--border)); border-radius: 2px; background: hsl(var(--card)); color: hsl(var(--card-foreground)); font-size: 0.875rem; }
 .scalio-license-part { padding: 1.25rem; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalio-cloud/ui",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Scalio Control Room design tokens, Tailwind preset, self-hosted fonts, the shared app header, sign-in layout, sidebar and page blocks",
   "license": "SEE LICENSE IN README.md",
   "private": false,

package/react/index.js

@@ -378,6 +378,6 @@ module.exports = {
   TEST_IDS,
   initials,
 };
-Object.assign(module.exports, Nav, Blocks, require("./settings"), require("./support"), require("./beacon"), require("./security"), require("./license"), require("./palette"), require("./unify"), require("./profile"), require("./actions"), require("./selftest"), require("./users"));
+Object.assign(module.exports, Nav, Blocks, require("./settings"), require("./support"), require("./beacon"), require("./security"), require("./license"), require("./palette"), require("./unify"), require("./profile"), require("./actions"), require("./selftest"), require("./users"), require("./wizard"));
 // After the exports above: auth.js uses LanguageToggle and ThemeToggle from this module.
 Object.assign(module.exports, require("./auth"));

package/react/labels.js

@@ -13,6 +13,19 @@ const LABELS = {
     userMenu: "Benutzermenü",
     menu: "Menü",
     version: "Version",
+    wizard: {
+      step: "Schritt {n} von {total}",
+      back: "Zurück",
+      next: "Weiter",
+      finish: "Einrichtung abschliessen",
+      skip: "Überspringen",
+      close: "Später",
+      done: "Los geht's",
+      successTitle: "Einrichtung abgeschlossen",
+      successText: "Alles ist bereit. Sie können jede Einstellung später unter Einstellungen ändern.",
+      open: "Einrichtungsassistent",
+      openHint: "Die Fragen der Ersteinrichtung noch einmal durchgehen.",
+    },
     // Sign-in and profile (same words in every app)
     signIn: "Anmelden",
     microsoft: "Mit Microsoft anmelden",
@@ -391,6 +404,19 @@ const LABELS = {
     userMenu: "User menu",
     menu: "Menu",
     version: "Version",
+    wizard: {
+      step: "Step {n} of {total}",
+      back: "Back",
+      next: "Continue",
+      finish: "Finish setup",
+      skip: "Skip",
+      close: "Later",
+      done: "Let's go",
+      successTitle: "Setup complete",
+      successText: "Everything is ready. You can change any setting later under Settings.",
+      open: "Setup wizard",
+      openHint: "Go through the first-time setup questions again.",
+    },
     signIn: "Sign in",
     microsoft: "Sign in with Microsoft",
     redirecting: "Redirecting …",
@@ -766,6 +792,7 @@ function labelsFor(lang, overrides) {
     accountTabs: Object.assign({}, base.accountTabs, o.accountTabs),
     passwordPolicy: Object.assign({}, base.passwordPolicy, o.passwordPolicy),
     profile_: Object.assign({}, base.profile_, o.profile_),
+    wizard: Object.assign({}, base.wizard, o.wizard),
   });
 }
 

package/react/wizard.js

@@ -0,0 +1,239 @@
+"use strict";
+// Setup wizard ("Einrichtungsassistent", ADR 0060, UISPEC section 3): the same first-step dialog in every app.
+// Design of the Nexus SetupWizard, first built in Kontor (#59): dialog, stepper on top, Zurück/Weiter, Überspringen
+// for optional steps, a short success message at the end. The shell knows no app: steps come as configuration.
+// Progress lives in the app's backend (GET/PUT /api/setup/wizard, scalio-docs interfaces/setup-wizard.md);
+// setupWizardApi() and useSetupWizard() do the wiring, so an app only writes its steps.
+const React = require("react");
+const h = React.createElement;
+const Icons = require("./icons");
+const { labelsFor } = require("./labels");
+const { Notice } = require("./blocks");
+
+const OPEN_SETUP_WIZARD = "scalio:open-setup-wizard";
+
+// Opens the wizard from anywhere (Einstellungen button, dashboard card). useSetupWizard listens for it.
+function openSetupWizard(step) {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new window.CustomEvent(OPEN_SETUP_WIZARD, { detail: { step: step || 0 } }));
+}
+
+function normalizeWizardState(d) {
+  const o = d || {};
+  const pick = (a, b) => (o[a] !== undefined ? o[a] : o[b]);
+  return {
+    needed: !!o.needed,
+    completed: !!o.completed,
+    lastStep: Number(pick("last_step", "lastStep")) || 0,
+    canEdit: pick("can_edit", "canEdit") === undefined ? true : !!pick("can_edit", "canEdit"),
+  };
+}
+
+// The shared route. `api` is the app's axios-like client (get/put returning { data }).
+function setupWizardApi(api, opts) {
+  const base = (opts && opts.base) || "/setup/wizard";
+  return {
+    get: () => api.get(base).then((r) => normalizeWizardState(r.data)),
+    save: (step) => api.put(base, { last_step: step }).then(() => true),
+    complete: () => api.put(base, { completed: true }).then(() => true),
+  };
+}
+
+// State, auto-open and saving for SetupWizard. Spread `props` into <SetupWizard> and add title and steps.
+// Opens by itself once per mount while the setup is needed and the person may edit it, at the saved step;
+// openSetupWizard() opens it again at the beginning. `closable: false` hides «Später» (e.g. nothing exists yet).
+function useSetupWizard(opts) {
+  const client = opts && opts.client;
+  const enabled = !opts || opts.enabled !== false;
+  const [state, setState] = React.useState(null);
+  const [open, setOpen] = React.useState(false);
+  const [step, setStep] = React.useState(0);
+  const auto = React.useRef(false);
+  const stateRef = React.useRef(null);
+  stateRef.current = state;
+
+  const reload = React.useCallback(() => {
+    if (!client) return Promise.resolve(null);
+    return client.get().then((s) => { setState(s); return s; }, () => null);
+  }, [client]);
+
+  React.useEffect(() => {
+    if (enabled) reload();
+  }, [enabled, reload]);
+
+  React.useEffect(() => {
+    if (state && state.needed && state.canEdit && !auto.current) {
+      auto.current = true;
+      setStep(state.lastStep);
+      setOpen(true);
+    }
+  }, [state]);
+
+  React.useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+    const onOpen = (e) => {
+      const s = stateRef.current;
+      if (s && !s.canEdit) return;
+      setStep((e && e.detail && e.detail.step) || 0);
+      setOpen(true);
+    };
+    window.addEventListener(OPEN_SETUP_WIZARD, onOpen);
+    return () => window.removeEventListener(OPEN_SETUP_WIZARD, onOpen);
+  }, []);
+
+  const close = () => setOpen(false);
+  const props = {
+    open,
+    step,
+    onStepChange: (n) => {
+      setStep(n);
+      if (client) client.save(n).catch(() => {});
+    },
+    onFinish: async () => {
+      if (client) await client.complete();
+      setState((s) => Object.assign({}, s, { needed: false, completed: true }));
+      if (opts && opts.onCompleted) opts.onCompleted();
+    },
+    onClose: opts && opts.closable === false ? undefined : close,
+    onDone: close,
+  };
+  return { state, open, setOpen, step, setStep, reload, props };
+}
+
+function StepDot({ index, current }) {
+  const cls = index < current ? "is-done" : index === current ? "is-current" : "";
+  return h("span", { className: `scalio-wizard-dot ${cls}`.trim() }, index < current ? h(Icons.Check, { width: 14, height: 14 }) : index + 1);
+}
+
+function SetupWizard(props) {
+  const { open, title, subtitle, steps, step, onStepChange, onFinish, onClose, firstStepAction, onDone, testId, wide } = props;
+  const L = Object.assign({}, labelsFor(props.lang).wizard, props.labels);
+  const success = props.success || { title: L.successTitle, text: L.successText };
+  const [busy, setBusy] = React.useState(false);
+  const [error, setError] = React.useState(null);
+  const [finished, setFinished] = React.useState(false);
+  const list = steps || [];
+  const index = Math.min(Math.max(step || 0, 0), list.length - 1);
+  const current = list[index];
+  const last = index === list.length - 1;
+
+  React.useEffect(() => setError(null), [index]);
+  React.useEffect(() => {
+    if (!open) setFinished(false);
+  }, [open]);
+  React.useEffect(() => {
+    if (!open || !onClose) return undefined;
+    const onKey = (e) => {
+      if (e.key === "Escape" && !busy) onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onClose, busy]);
+
+  if (!open || !current) return null;
+
+  async function next(save) {
+    setBusy(true);
+    setError(null);
+    try {
+      if (save && current.onNext) await current.onNext();
+      if (last) {
+        await onFinish();
+        setFinished(true);
+      } else {
+        onStepChange(index + 1);
+      }
+    } catch (err) {
+      setError((err && err.message) || String(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const left = index > 0
+    ? { label: L.back, onClick: () => onStepChange(index - 1) }
+    : firstStepAction || (onClose ? { label: L.close, onClick: onClose } : null);
+
+  const head = h(
+    "div",
+    { className: "scalio-wizard-head" },
+    h("div", null,
+      h("h2", { className: "scalio-wizard-title" }, title),
+      subtitle && !finished ? h("p", { className: "scalio-wizard-subtitle" }, subtitle) : null),
+    onClose
+      ? h("button", { type: "button", className: "scalio-btn scalio-btn-icon is-ghost", onClick: onClose, "aria-label": L.close, "data-testid": "wizard-close" },
+          h(Icons.X, null))
+      : null
+  );
+
+  const body = finished
+    ? h(
+        "div",
+        { className: "scalio-wizard-success", "data-testid": "wizard-success" },
+        h("span", { className: "scalio-wizard-success-icon" }, h(Icons.Check, { width: 24, height: 24 })),
+        h("h3", { className: "scalio-wizard-step-title" }, success.title),
+        h("p", { className: "scalio-wizard-text" }, success.text),
+        h("button", { type: "button", className: "scalio-btn is-primary", onClick: onDone || onClose, "data-testid": "wizard-done", autoFocus: true }, L.done)
+      )
+    : h(
+        React.Fragment,
+        null,
+        h(
+          "ol",
+          { className: "scalio-wizard-stepper", "data-testid": "wizard-stepper" },
+          list.map((s, i) =>
+            h(
+              "li",
+              { key: s.id, className: "scalio-wizard-stepper-item", "data-testid": "wizard-stepper-item", "aria-current": i === index ? "step" : undefined },
+              h(StepDot, { index: i, current: index }),
+              h("span", { className: `scalio-wizard-label${i === index ? " is-current" : ""}` }, s.label),
+              i < list.length - 1 ? h("span", { className: "scalio-wizard-line" }) : null
+            )
+          )
+        ),
+        h("p", { className: "scalio-wizard-count" }, L.step.replace("{n}", String(index + 1)).replace("{total}", String(list.length))),
+        h(
+          "section",
+          { className: "scalio-wizard-step", "data-testid": `wizard-step-${current.id}` },
+          h("div", null,
+            h("h3", { className: "scalio-wizard-step-title" }, current.title),
+            current.description ? h("p", { className: "scalio-wizard-text" }, current.description) : null),
+          current.content
+        ),
+        error ? h(Notice, { kind: "error", icon: false, testId: "wizard-error", lang: props.lang }, error) : null,
+        h(
+          "div",
+          { className: "scalio-wizard-actions" },
+          left
+            ? h("button", { type: "button", className: "scalio-btn", onClick: left.onClick, disabled: busy, "data-testid": "wizard-back" }, left.label)
+            : h("span", null),
+          h(
+            "div",
+            { className: "scalio-wizard-actions-right" },
+            current.optional
+              ? h("button", { type: "button", className: "scalio-btn is-ghost", onClick: () => next(false), disabled: busy, "data-testid": "wizard-skip" }, L.skip)
+              : null,
+            h(
+              "button",
+              { type: "button", className: "scalio-btn is-primary", onClick: () => next(true), disabled: busy || current.canNext === false, "data-testid": "wizard-next" },
+              busy ? h("span", { className: "scalio-spinner", "aria-hidden": "true" }) : null,
+              last ? L.finish : L.next
+            )
+          )
+        )
+      );
+
+  return h(
+    "div",
+    { className: "scalio-wizard-root", onMouseDown: (e) => { if (e.target === e.currentTarget && !busy && onClose) onClose(); } },
+    h("div", { role: "dialog", "aria-modal": "true", "aria-label": title, className: wide ? "scalio-wizard is-wide" : "scalio-wizard", "data-testid": testId || "setup-wizard" }, head, body)
+  );
+}
+
+// Button for Einstellungen (UISPEC: the wizard can always be opened again, by people who may edit the setup).
+function SetupWizardButton({ lang, labels, testId, className }) {
+  const L = Object.assign({}, labelsFor(lang).wizard, labels);
+  return h("button", { type: "button", className: className || "scalio-btn", onClick: () => openSetupWizard(0), "data-testid": testId || "settings-open-wizard", title: L.openHint }, L.open);
+}
+
+module.exports = { SetupWizard, SetupWizardButton, useSetupWizard, setupWizardApi, normalizeWizardState, openSetupWizard, OPEN_SETUP_WIZARD };