@eintrek/erp-shell 0.1.66 → 0.1.67

package/dist/guide/dom.d.ts

@@ -38,6 +38,8 @@ export declare const OPEN_DIALOG_SELECTOR = "[role=\"dialog\"][data-state=\"open
  * behind it.
  */
 export declare function coveredByDialog(el: Element | null): boolean;
+/** An app dialog (not the tour's) is open on the page. */
+export declare function appDialogOpen(): boolean;
 export declare function openPoppers(): HTMLElement[];
 export declare function inGuideLayer(node: EventTarget | null): boolean;
 export declare function prefersReducedMotion(): boolean;

package/dist/guide/machine.d.ts

@@ -44,6 +44,9 @@ export type GuideScreen = {
     /** A `hidden` trigger's anchor has been seen on this step, so its
      *  going away counts. */
     armed: boolean;
+    /** A commit step shown in its read form: nothing to save
+     *  (GuideStep.nothingToSave). */
+    nothingToSave: boolean;
 } | {
     name: "celebrate";
     mission: string;
@@ -63,6 +66,18 @@ export interface GuideState {
     nudge: number;
     /** The gate card was put away for this visit ("ไว้ทีหลัง"). */
     gateDismissed: boolean;
+    /**
+     * What the user already had open when the current replay started: those
+     * are theirs, and ending the replay leaves them alone (see pushAbort).
+     */
+    replayPage: ReplayPage | null;
+}
+export interface ReplayPage {
+    mission: string;
+    /** The mission's abort anchors that were on the page at the start. */
+    anchors: string[];
+    /** An app dialog was open at the start. */
+    dialog: boolean;
 }
 /** What the machine may ask about the page. */
 export interface GuideEnv {
@@ -77,6 +92,8 @@ export interface GuideEnv {
     sidebarOpen: boolean;
     /** The current value of the step target's field. */
     targetValue: () => string;
+    /** An app dialog (not the tour's) is open. */
+    dialogOpen?: () => boolean;
 }
 export type GuideSignal = {
     kind: "api";
@@ -213,6 +230,16 @@ export declare function triggersOf(step: GuideStep): GuideTrigger[];
 export declare function stepKind(step: GuideStep): import("./types").GuideStepKind;
 /** The last checkpoint at or before `index` (a mission's first step always is one). */
 export declare function checkpointAtOrBefore(steps: GuideStep[], index: number): number;
+/**
+ * A commit step with nothing to save: its button is not on the page, and what
+ * is saved is (GuideStep.nothingToSave).
+ */
+export declare function nothingToSaveHolds(step: GuideStep, env: GuideEnv, ctx: GuideContext): boolean;
+/**
+ * The step as it is shown: a commit step with nothing to save is a read step
+ * on what is saved, with its own title (ถัดไป moves on).
+ */
+export declare function shownStep(step: GuideStep, nothingToSave: boolean): GuideStep;
 /** Whether the step's target (or the bridge's) is on screen. */
 export declare function stepTargetVisible(step: GuideStep, env: GuideEnv, ctx: GuideContext, bridge: boolean): boolean;
 /** The anchor the spotlight is on for the current step. */
@@ -228,6 +255,14 @@ export declare function spotlightTarget(step: GuideStep, ctx: GuideContext, brid
 export declare function stepHomeRoute(steps: GuideStep[], index: number): string | undefined;
 /** What puts the page back when a replay ends at this step (see GuideStep.abort). */
 export declare function abortActionsFor(mission: GuideMission, index: number): GuideAbortAction[];
+/** Every anchor the mission's abort actions press. */
+export declare function abortAnchorsOf(mission: GuideMission): string[];
+/**
+ * What the replay may do to put the page back: not press what the user had
+ * open before it started, not Escape out of a dialog that was already open,
+ * and no app event while anything of theirs was open.
+ */
+export declare function abortActionsLeft(actions: GuideAbortAction[], before: ReplayPage | null): GuideAbortAction[];
 /** Status of each mission as the panel shows it. */
 export type MissionView = "todo" | "next" | "active" | "skipped" | "done" | "already" | "locked" | "waiting";
 export declare function missionSettled(m: GuideMission, entry: MissionEntry | undefined, ctx: GuideContext): boolean;

package/dist/guide/types.d.ts

@@ -180,6 +180,17 @@ export interface GuideStep {
      * or Escape to the open dialog. Overrides the mission's `abort`.
      */
     abort?: GuideAbortAction | GuideAbortAction[];
+    /**
+     * "commit" steps whose button only shows after a change (a save bar that
+     * appears once the form is edited). When `target` is not on the page but
+     * `nothingToSave.target` is (what is saved is on screen and nothing is
+     * changed), the step is a read step on that anchor, with ถัดไป, which moves
+     * on as if saved. The moment `target` shows (the user changed something)
+     * it is the commit step again. Name an anchor that only exists when the
+     * saved state is real, so a first run never passes without a save that
+     * was needed (shell ≥ 0.1.67).
+     */
+    nothingToSave?: GuideNothingToSave;
     /**
      * "commit" steps: what a refused save means. Return the key of the step to
      * go back to (a field) and/or the line to show. Default: stay, show the
@@ -190,10 +201,20 @@ export interface GuideStep {
         message?: string;
     } | void;
 }
+/** A commit step's read form when there is nothing to save (GuideStep.nothingToSave). */
+export interface GuideNothingToSave {
+    /** What is saved, on screen (the placed point's card, the saved list). */
+    target: GuideAnchorKey;
+    title: GuideText;
+    why?: GuideText;
+    /** Anchors the user may use meanwhile; a change there brings the save back. */
+    allow?: GuideAnchorKey[];
+}
 /**
  * One thing the engine does to put the page back when a replay ends early.
  * Run in order, after the tour has let go of the page; an anchor that is not
- * on the page is passed over.
+ * on the page is passed over, and so is one that was already on the page
+ * when the replay started (the user's own open form: shell ≥ 0.1.67).
  */
 export type GuideAbortAction = 
 /** Press this anchor (the form's ยกเลิก, a dialog's close). */
@@ -251,6 +272,9 @@ export interface GuideMission {
      * How to put the page back when a replay of this mission ends without
      * saving (a step's own `abort` wins). Default: Escape, and only from a step
      * that is not a checkpoint (inside the dialog or form the tour opened).
+     * Whatever was already open when the replay started is the user's and is
+     * left alone: an anchor on the page then is never pressed, and no Escape
+     * is sent when an app dialog was open (shell ≥ 0.1.67).
      */
     abort?: GuideAbortAction | GuideAbortAction[];
     steps: GuideStep[];

package/dist/index.d.ts

@@ -33,7 +33,7 @@ export { HelpDialogHost, type HelpDialogHostProps } from "./help/help-dialog";
 export { openHelp, closeHelp, type HelpAppId } from "./help/help-store";
 export { describeBrowser, describeAttached, detectHelpApp, type HelpContext, } from "./help/help-context";
 export { SHELL_VERSION } from "./version";
-export type { GuideAbortAction, GuideAnchorKey, GuideApiFailure, GuideApiMatch, GuideAppId, GuideCaptureEvent, GuideConfig, GuideContext, GuideFacts, GuideGate, GuideMission, GuideOnMissing, GuideStep, GuideStepKind, GuideSuite, GuideText, GuideTrigger, } from "./guide/types";
+export type { GuideAbortAction, GuideAnchorKey, GuideApiFailure, GuideApiMatch, GuideAppId, GuideCaptureEvent, GuideConfig, GuideContext, GuideFacts, GuideGate, GuideMission, GuideNothingToSave, GuideOnMissing, GuideStep, GuideStepKind, GuideSuite, GuideText, GuideTrigger, } from "./guide/types";
 export { API_EVENT as GUIDE_API_EVENT, GUIDE_EVENT_PREFIX, GUIDE_LAYER_ATTRIBUTE, emitGuideEvent, guideAnchor, reportApiEvent, type ApiEventDetail, type GuideAnchorProps, } from "./guide/events";
 export { openGuidePanel, useGuideEntry, type GuideEntry } from "./guide/guide-store";
 export { GuideHost, type GuideHostProps } from "./guide/guide-host";

package/dist/index.esm.js

@@ -1956,7 +1956,7 @@ function platformApiBase(app) {
  * This package's version, attached to help messages so the back office can
  * tell which shell a report came from. Keep in step with package.json.
  */
-const SHELL_VERSION = "0.1.66";
+const SHELL_VERSION = "0.1.67";
 
 const HELP_APP_LABEL = {
     platform: "แพลตฟอร์ม",
@@ -3813,6 +3813,7 @@ function initialGuideState(audience, progress) {
         chipPulse: 0,
         nudge: 0,
         gateDismissed: false,
+        replayPage: null,
     };
 }
 function findMission(suite, key) {
@@ -3870,6 +3871,38 @@ function targetIdOf(step, ctx) {
         return safe(() => step.targetId(ctx), undefined);
     return step.targetId;
 }
+/**
+ * A commit step with nothing to save: its button is not on the page, and what
+ * is saved is (GuideStep.nothingToSave).
+ */
+function nothingToSaveHolds(step, env, ctx) {
+    const n = step.nothingToSave;
+    if (!n || !step.target)
+        return false;
+    return !env.isVisible(step.target, targetIdOf(step, ctx)) && env.isVisible(n.target);
+}
+/**
+ * The step as it is shown: a commit step with nothing to save is a read step
+ * on what is saved, with its own title (ถัดไป moves on).
+ */
+function shownStep(step, nothingToSave) {
+    const n = step.nothingToSave;
+    if (!nothingToSave || !n)
+        return step;
+    return {
+        key: step.key,
+        kind: "view",
+        target: n.target,
+        title: n.title,
+        why: n.why,
+        allow: n.allow,
+        route: step.route,
+        resumeUrl: step.resumeUrl,
+        checkpoint: step.checkpoint,
+        timeoutMs: step.timeoutMs,
+        abort: step.abort,
+    };
+}
 /** Whether the step's target (or the bridge's) is on screen. */
 function stepTargetVisible(step, env, ctx, bridge) {
     if (bridge)
@@ -3938,6 +3971,30 @@ function abortActionsFor(mission, index) {
         return [];
     return [{ escape: true }];
 }
+/** Every anchor the mission's abort actions press. */
+function abortAnchorsOf(mission) {
+    const out = new Set();
+    const add = (a) => {
+        for (const x of a ? (Array.isArray(a) ? a : [a]) : [])
+            if ("click" in x)
+                out.add(x.click);
+    };
+    add(mission.abort);
+    for (const st of mission.steps)
+        add(st.abort);
+    return Array.from(out);
+}
+/**
+ * What the replay may do to put the page back: not press what the user had
+ * open before it started, not Escape out of a dialog that was already open,
+ * and no app event while anything of theirs was open.
+ */
+function abortActionsLeft(actions, before) {
+    if (!before)
+        return actions;
+    const busy = before.anchors.length > 0 || before.dialog;
+    return actions.filter(a => "click" in a ? !before.anchors.includes(a.click) : "escape" in a ? !before.dialog : !busy);
+}
 function routeParamsFor(step, env) {
     if (!step.route)
         return {};
@@ -4076,7 +4133,7 @@ function announceStep(d, suite, env) {
     const mission = findMission(suite, s.mission);
     if (!mission)
         return;
-    const step = mission.steps[s.index];
+    const step = shownStep(mission.steps[s.index], s.nothingToSave);
     const ctx = guideContext(env, d.state.progress.context, routeParamsFor(step, env));
     const title = s.bridge ? COPY.bridgeTitle : plainTitle(resolveText(step.title, ctx));
     const why = s.bridge ? COPY.bridgeWhy(suite.appName) : plainTitle(resolveText(step.why, ctx));
@@ -4144,6 +4201,7 @@ function enterStep(d, suite, env, mission, index, opts) {
         confirmExit: false,
         misses: 0,
         armed: hiddenAnchorShown(step, env),
+        nothingToSave: !away && !bridge && nothingToSaveHolds(step, env, ctx),
     });
     if (!opts.replay) {
         const cp = checkpointAtOrBefore(steps, i);
@@ -4161,6 +4219,28 @@ function enterStep(d, suite, env, mission, index, opts) {
         markReadyIfVisible(d, suite, env);
     }
 }
+/**
+ * The save button came (a change) or went (nothing left to save): show the
+ * commit step's other form. A ready step whose new target is not there is
+ * left to the target-lost path (back to the checkpoint).
+ */
+function setNothingToSave(d, suite, env, on) {
+    const s = d.state.screen;
+    if (s.name !== "step" || s.nothingToSave === on)
+        return;
+    setScreen(d, { ...s, nothingToSave: on, error: null });
+    if (s.phase !== "ready") {
+        markReadyIfVisible(d, suite, env);
+        return;
+    }
+    const mission = findMission(suite, s.mission);
+    if (!mission)
+        return;
+    const step = shownStep(mission.steps[s.index], on);
+    const ctx = guideContext(env, d.state.progress.context, routeParamsFor(step, env));
+    if (stepTargetVisible(step, env, ctx, s.bridge))
+        announceStep(d, suite, env);
+}
 function markReadyIfVisible(d, suite, env) {
     const s = d.state.screen;
     if (s.name !== "step" || s.phase !== "waiting")
@@ -4168,7 +4248,7 @@ function markReadyIfVisible(d, suite, env) {
     const mission = findMission(suite, s.mission);
     if (!mission)
         return;
-    const step = mission.steps[s.index];
+    const step = shownStep(mission.steps[s.index], s.nothingToSave);
     const ctx = guideContext(env, d.state.progress.context, routeParamsFor(step, env));
     if (stepTargetVisible(step, env, ctx, s.bridge)) {
         setScreen(d, { ...s, phase: "ready" });
@@ -4290,6 +4370,17 @@ function startMission(d, suite, env, key, replay) {
         if (at > 0)
             index = checkpointAtOrBefore(mission.steps, at);
     }
+    if (isReplay) {
+        // What is open now is the user's: ending the replay leaves it alone.
+        d.state = {
+            ...d.state,
+            replayPage: {
+                mission: key,
+                anchors: abortAnchorsOf(mission).filter(a => safe(() => env.isVisible(a), false)),
+                dialog: safe(() => env.dialogOpen?.() === true, false),
+            },
+        };
+    }
     enterStep(d, suite, env, mission, index, { replay: isReplay });
     // A replay never writes progress; only what starting it changed (the
     // welcome, first seen through a replay) is saved.
@@ -4350,7 +4441,8 @@ function pushAbort(d, suite, s) {
     const mission = findMission(suite, s.mission);
     if (!mission)
         return;
-    const actions = abortActionsFor(mission, s.index);
+    const before = d.state.replayPage?.mission === s.mission ? d.state.replayPage : null;
+    const actions = abortActionsLeft(abortActionsFor(mission, s.index), before);
     if (actions.length)
         d.effects.push({ type: "abort", actions });
 }
@@ -4443,7 +4535,12 @@ function reduceGuide(state, action, suite, env) {
             }
             if (s.confirmExit)
                 break;
-            const kind = stepKind(step);
+            const nts = !s.bridge && nothingToSaveHolds(step, env, ctx);
+            if (nts !== s.nothingToSave) {
+                setNothingToSave(d, suite, env, nts);
+                break;
+            }
+            const kind = stepKind(shownStep(step, s.nothingToSave));
             const armed = s.armed || hiddenAnchorShown(step, env);
             if (kind !== "input" && kind !== "view") {
                 const held = syncTriggerHolds(step, env, armed);
@@ -4452,7 +4549,7 @@ function reduceGuide(state, action, suite, env) {
                     break;
                 }
             }
-            if (!s.bridge && !stepTargetVisible(step, env, ctx, false) && offRoute(mission.steps, s.index, env)) {
+            if (!s.bridge && !stepTargetVisible(shownStep(step, s.nothingToSave), env, ctx, false) && offRoute(mission.steps, s.index, env)) {
                 // The target is missing because the page is another one.
                 recoverOffRoute(d, suite, env, false);
                 break;
@@ -4523,8 +4620,9 @@ function reduceGuide(state, action, suite, env) {
             if (!mission)
                 break;
             const step = mission.steps[s.index];
-            const kind = stepKind(step);
+            const kind = stepKind(shownStep(step, s.nothingToSave));
             if (kind === "view") {
+                // A read step, or a commit step with nothing to save.
                 advance(d, suite, env);
                 break;
             }
@@ -4553,21 +4651,24 @@ function reduceGuide(state, action, suite, env) {
             const mission = findMission(suite, s.mission);
             if (!mission)
                 break;
-            const step = mission.steps[s.index];
-            const ctx = guideContext(env, d.state.progress.context, routeParamsFor(step, env));
-            if (stepTargetVisible(step, env, ctx, s.bridge))
+            const raw = mission.steps[s.index];
+            const ctx = guideContext(env, d.state.progress.context, routeParamsFor(raw, env));
+            // The save went with nothing left to save, or came back: the other form.
+            setNothingToSave(d, suite, env, !s.bridge && nothingToSaveHolds(raw, env, ctx));
+            const cur = d.state.screen;
+            if (stepTargetVisible(shownStep(raw, cur.nothingToSave), env, ctx, cur.bridge))
                 break;
-            if (!s.bridge && offRoute(mission.steps, s.index, env)) {
+            if (!cur.bridge && offRoute(mission.steps, cur.index, env)) {
                 recoverOffRoute(d, suite, env, false);
                 break;
             }
-            const cp = checkpointAtOrBefore(mission.steps, s.index);
-            if (cp < s.index && !s.bridge) {
+            const cp = checkpointAtOrBefore(mission.steps, cur.index);
+            if (cp < cur.index && !cur.bridge) {
                 // A dialog or a menu closed under the step: back to what opens it.
-                enterStep(d, suite, env, mission, cp, { replay: s.replay, noAutoPass: false });
+                enterStep(d, suite, env, mission, cp, { replay: cur.replay, noAutoPass: false });
             }
             else {
-                setScreen(d, { ...s, phase: "waiting" });
+                setScreen(d, { ...cur, phase: "waiting" });
             }
             break;
         }
@@ -5159,6 +5260,12 @@ function coveredByDialog(el) {
     }
     return false;
 }
+/** An app dialog (not the tour's) is open on the page. */
+function appDialogOpen() {
+    if (!hasDocument())
+        return false;
+    return Array.from(document.querySelectorAll(OPEN_DIALOG_SELECTOR)).some(d => !inGuideLayer(d) && isPresent(d));
+}
 function openPoppers() {
     if (!hasDocument())
         return [];
@@ -6197,6 +6304,7 @@ function GuideHostInner({ config, organizationId, code }) {
             isVisible: (anchor, id) => anchorVisible(anchor, id),
             sidebarOpen: pg.sidebarOpen,
             targetValue: () => fieldValue(targetElRef.current),
+            dialogOpen: () => appDialogOpen(),
         };
     }, [code]);
     /* ---------------- effects: save, announce, toast, navigate ---------------- */
@@ -6373,11 +6481,13 @@ function GuideHostInner({ config, organizationId, code }) {
         const mission = findMission(suite, screen.mission);
         if (!mission)
             return null;
-        const step = mission.steps[screen.index];
-        if (!step)
+        const raw = mission.steps[screen.index];
+        if (!raw)
             return null;
+        // A commit step with nothing to save is shown as its read form.
+        const step = shownStep(raw, screen.nothingToSave);
         const missionNo = suite.missions.indexOf(mission) + 1;
-        return { mission, step, missionNo };
+        return { mission, step, raw, missionNo };
     }, [state, screen, suite]);
     const stepCtx = useMemo(() => {
         if (!state)
@@ -6393,7 +6503,7 @@ function GuideHostInner({ config, organizationId, code }) {
         : null;
     const targetKey = target ? `${target.anchor}|${target.id ?? ""}` : "";
     const phase = screen.name === "step" ? screen.phase : null;
-    const stepId = screen.name === "step" ? `${screen.mission}:${screen.index}:${screen.bridge ? "b" : ""}` : "";
+    const stepId = screen.name === "step" ? `${screen.mission}:${screen.index}:${screen.bridge ? "b" : ""}${screen.nothingToSave ? "n" : ""}` : "";
     /* Measure every frame while a step is shown: the spotlight follows
        scrolling, dialogs animating in, the drawer sliding, the keyboard. */
     const [layout, setLayout] = useState({
@@ -6556,7 +6666,7 @@ function GuideHostInner({ config, organizationId, code }) {
             dispatchRef.current({ type: "signal", signal: { kind: "api", method: d.method, path: d.path, status: d.status, id: d.id, message: d.message } });
         };
         window.addEventListener(API_EVENT, onApi);
-        const names = triggersOf(stepInfo.step).flatMap(t => ("event" in t ? [t.event] : []));
+        const names = triggersOf(stepInfo.raw).flatMap(t => ("event" in t ? [t.event] : []));
         const onApp = (name) => (e) => dispatchRef.current({ type: "signal", signal: { kind: "event", name, detail: e.detail ?? undefined } });
         const appHandlers = names.map(n => [GUIDE_EVENT_PREFIX + n, onApp(n)]);
         appHandlers.forEach(([n, h]) => window.addEventListener(n, h));