@eintrek/erp-shell 0.1.61 → 0.1.63

package/dist/guide/progress.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A tour's progress as platform-api stores it (one row per user, org and
+ * suite: GET/PUT /organizations/:id/guides/me), and the rules for reading,
+ * writing and merging it. See _claude-work/peoplx-guide/API.md.
+ *
+ * No runtime imports: the tests run this file in Node as it is.
+ */
+export type GuideMode = "off" | "invite" | "forced";
+export type GuideAudience = "forced" | "optional" | "none";
+export type GuideRowStatus = "in_progress" | "completed" | "skipped" | "aborted";
+export type MissionStatus = "todo" | "active" | "done" | "skipped";
+export type WelcomeState = "not_seen" | "started" | "skipped";
+export interface MissionEntry {
+    status: MissionStatus;
+    step_key?: string | null;
+    skipped_step?: string | null;
+    /** Server-written. */
+    completed_at?: string | null;
+    /** Server-written. */
+    skipped_at?: string | null;
+}
+/** The row, as the client keeps it. */
+export interface GuideProgress {
+    guide_version: number;
+    /** The rev of the row last read; 0 when there is none. */
+    rev: number;
+    status: GuideRowStatus;
+    mission_key: string | null;
+    step_key: string | null;
+    step_index: number;
+    checkpoint_key: string | null;
+    missions: Record<string, MissionEntry>;
+    context: Record<string, string>;
+    welcome: WelcomeState;
+    chip_hidden: boolean;
+    last_error: string | null;
+    skipped_step: string | null;
+    /** The status the server holds (to know when a PUT needs restart: true). */
+    server_status: GuideRowStatus | null;
+}
+export interface GuidesAnswer {
+    mode: GuideMode;
+    audience: GuideAudience;
+    /** The suite's row; a fresh one when the user has none or an older version. */
+    progress: GuideProgress;
+    /** The server holds a newer version than this app's tour: do not run. */
+    newerOnServer: boolean;
+}
+export declare function freshProgress(version: number, rev?: number): GuideProgress;
+/** One row (a GET `guides[]` entry, a PUT answer, a 409's `current`). Null when off-shape. */
+export declare function parseRow(raw: unknown): GuideProgress | null;
+/**
+ * The GET answer for one suite. Null — show nothing — for anything that is
+ * not the expected shape (an older API, a proxy's page, another app's answer).
+ */
+export declare function parseGuidesAnswer(payload: unknown, suite: {
+    key: string;
+    version: number;
+    app: string;
+}): GuidesAnswer | null;
+/** The PUT body for the client's state. Drops keys the server would refuse. */
+export declare function putBody(p: GuideProgress, app: string): Record<string, unknown>;
+/**
+ * After a 409: this tab's state laid over the server's, keeping whatever is
+ * further along — a mission done anywhere stays done, the welcome once seen
+ * stays seen, a hidden chip stays hidden. Otherwise this tab's own choice
+ * wins. The rev is the server's.
+ */
+export declare function mergeProgress(local: GuideProgress, remote: GuideProgress): GuideProgress;
+/**
+ * Which of two copies (sessionStorage after F5, the server) to resume from:
+ * the one further along for the same version; the server's on a tie.
+ */
+export declare function furtherProgress(a: GuideProgress, b: GuideProgress): GuideProgress;

package/dist/guide/types.d.ts

@@ -0,0 +1,288 @@
+/**
+ * The guided tour ("ไกด์เริ่มต้น"): what an app writes to describe its tour.
+ *
+ * A tour is data. The app hands a GuideSuite to AppLayoutShell's `guides`
+ * prop; the shell's engine runs it — the spotlight, the bubble, the quest
+ * chip — and saves progress on platform-api. Functions in here are small
+ * predicates and text builders, never engine code.
+ *
+ * No runtime imports: the tests run this file in Node as it is.
+ * The full guide for tour authors is _claude-work/peoplx-guide/ENGINE-API.md.
+ */
+/** Which app a tour belongs to (the same ids as the help channel). */
+export type GuideAppId = "platform" | "accounx" | "invenx" | "plannex" | "peoplx" | "sellx" | "carex";
+/**
+ * A `data-guide` key, "<app>.<area>.<element>" — "peoplx.shift.edit".
+ * The shell's own: "nav.<menu item id>", "shell.menu-toggle", "shell.help".
+ */
+export type GuideAnchorKey = string;
+/** Values the app passes in (`guides.facts`) for predicates to read. */
+export type GuideFacts = Readonly<Record<string, unknown>>;
+/** What every predicate and text builder gets. */
+export interface GuideContext {
+    /** The organisation code in the URL ("O26000021"). */
+    code: string;
+    /** The current path, without the query. */
+    pathname: string;
+    /** The current query. */
+    search: URLSearchParams;
+    /**
+     * Route params from the step's `route` pattern (`/[code]/employee/[id]` →
+     * `{ code, id }`), when the page matches it.
+     */
+    params: Readonly<Record<string, string>>;
+    /** Ids captured by earlier steps of this mission (`capture`). */
+    data: Readonly<Record<string, string>>;
+    /** The app's facts (counts, flags), as passed to the shell. */
+    facts: GuideFacts;
+    /** The app's permission check (`guides.can`); true when none was given. */
+    can: (policyKey: string) => boolean;
+    /** Whether an anchor is on screen now. */
+    visible: (anchor: GuideAnchorKey) => boolean;
+}
+/** Text that may depend on the context. */
+export type GuideText = string | ((ctx: GuideContext) => string);
+/**
+ * What moves a step on. A step lists one or several (any of them advances).
+ * Prefer outcomes over clicks: a route reached, a dialog shown, a 2xx.
+ */
+export type GuideTrigger = 
+/** The page is this route. Next-style pattern; an optional `?k=v` must be
+ *  in the query. `/[code]/setting?tab=department` */
+{
+    route: string;
+}
+/** The anchor appeared (a dialog, a select's list, a tab panel). */
+ | {
+    visible: GuideAnchorKey;
+}
+/** The anchor went away (a dialog closed). */
+ | {
+    hidden: GuideAnchorKey;
+}
+/** A call through the shell's axios (or reportApiEvent) answered. */
+ | {
+    api: GuideApiMatch;
+}
+/** `emitGuideEvent(name)` was called (window event `erp:guide:<name>`). */
+ | {
+    event: string;
+}
+/** The target was pressed (pointer, Enter or Space). Last resort. */
+ | {
+    activate: true;
+}
+/** The value of the target's input/select/textarea now passes. */
+ | {
+    value: (value: string, ctx: GuideContext) => boolean;
+};
+export interface GuideApiMatch {
+    /** GET, POST, PUT, PATCH, DELETE. Any method when omitted. */
+    method?: string;
+    /**
+     * The path, matched against the END of the request's path (any base URL
+     * and query removed): "/shifts/[id]", "/departments". `[x]` and `:x` match
+     * one segment, `*` any number. A RegExp is tested against the whole path.
+     */
+    path: string | RegExp;
+    /** Default "2xx". */
+    status?: "2xx" | number;
+}
+/** How a step is shown and what its bubble offers. */
+export type GuideStepKind = 
+/** Press the target; moves on when what follows happens. Hand shown. */
+"click"
+/** Type into the target; moves on with Enter / ถัดไป / Tab when `validate`
+ *  passes. No hand. */
+ | "input"
+/** Choose a value; moves on as soon as `advanceOn` fires. Hand shown. */
+ | "select"
+/** Save; moves on only on the API's 2xx. In a replay the bubble offers
+ *  "จบโดยไม่บันทึก". Hand shown. */
+ | "commit"
+/** Read; moves on with ถัดไป. No hand. `target` optional. */
+ | "view";
+export type GuideOnMissing = "retry" | "skip" | "rewind" | "abort";
+export interface GuideApiFailure {
+    status: number;
+    /** The server's message, when it sent one. */
+    message?: string;
+}
+export interface GuideStep {
+    /** Stable id, saved on the server. Never reuse a key for another step. */
+    key: string;
+    kind?: GuideStepKind;
+    /**
+     * The anchor to spotlight. For a field, anchor the wrapper (label, input,
+     * error line); the engine types into the first input inside it.
+     */
+    target?: GuideAnchorKey;
+    /** Pick the target with this `data-guide-id` among repeated rows. */
+    targetId?: string | ((ctx: GuideContext) => string | undefined);
+    /**
+     * The instruction, one line (≈30 characters). A word in [brackets] is
+     * drawn as a chip in the brand colour: "กด [ตั้งค่า HR]".
+     */
+    title: GuideText;
+    /** One short line on why (≈45 characters). Optional. */
+    why?: GuideText;
+    /**
+     * Where the step happens (pattern as in `{ route }`). Used to resume after
+     * a refresh and to send the user back when they are elsewhere.
+     */
+    route?: string;
+    /** Where to send the user to resume at this step; `route` with the
+     *  context's params filled in when omitted. */
+    resumeUrl?: (ctx: GuideContext) => string | undefined;
+    /**
+     * A step the tour can restart from: on a stable page, not inside a dialog
+     * or a menu. A refresh, a closed dialog or a lost target goes back to the
+     * last checkpoint. A mission's first step always is one.
+     */
+    checkpoint?: boolean;
+    /** What moves the step on. "view" and "input" steps need none. */
+    advanceOn?: GuideTrigger | GuideTrigger[];
+    /**
+     * When the step is entered, a `route` or `visible` trigger that already
+     * holds passes it at once (the user is already on the page). Default true;
+     * false keeps the step.
+     */
+    autoPass?: boolean;
+    /**
+     * "input" steps: null when the value is fine, otherwise the line to show
+     * ("ยังไม่ได้พิมพ์ชื่อแผนก"). Default: not blank.
+     */
+    validate?: (value: string, ctx: GuideContext) => string | null;
+    /**
+     * Ids to remember for later steps (privacy: ids only, never typed values).
+     * `api.id` is the saved record's id (data.id or data.data.id).
+     */
+    capture?: (e: GuideCaptureEvent, ctx: GuideContext) => Record<string, string> | void;
+    /** Skip the step (silently) when true. Runs every time it is entered. */
+    skipIf?: (ctx: GuideContext) => boolean;
+    /** A policy key the step needs (checked with `guides.can`); skipped when
+     *  the user lacks it. */
+    requires?: string;
+    /** When the target never shows. Default "retry" (then back to the last
+     *  checkpoint on a second miss). */
+    onMissing?: GuideOnMissing;
+    /** How long to wait for the target, while nothing is loading. 8000 ms. */
+    timeoutMs?: number;
+    /** More anchors the user may use during this step. */
+    allow?: GuideAnchorKey[];
+    /**
+     * "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
+     * server's message.
+     */
+    onApiError?: (failure: GuideApiFailure, ctx: GuideContext) => {
+        step?: string;
+        message?: string;
+    } | void;
+}
+/** What `capture` sees: the trigger that advanced the step. */
+export interface GuideCaptureEvent {
+    route?: {
+        pathname: string;
+        params: Readonly<Record<string, string>>;
+    };
+    api?: {
+        method: string;
+        path: string;
+        status: number;
+        id?: string;
+    };
+    event?: {
+        name: string;
+        detail?: Readonly<Record<string, string>>;
+    };
+}
+export interface GuideMission {
+    /** Stable id within the suite, saved on the server: "work-hours". */
+    key: string;
+    /** What it achieves, ≈20 characters: "ตั้งเวลาทำงาน". */
+    title: string;
+    /** Rough minutes, for "ประมาณ 2 นาที". */
+    minutes: number;
+    /** Missions that must be done first ("ทำ <ชื่อ> ก่อน"). */
+    after?: string[];
+    /** The user may set it aside for good ("ไม่ใช้ภารกิจนี้"); it then counts
+     *  as settled for completion. */
+    optional?: boolean;
+    /**
+     * The org already has what this mission makes: shown as "ทำไว้แล้ว" with
+     * "ดูวิธีทำ" (a replay). undefined = not known yet.
+     */
+    alreadyDone?: (ctx: GuideContext) => boolean | undefined;
+    /** The celebration. Title defaults to "<title>แล้ว". */
+    done?: {
+        title?: GuideText;
+        subtitle?: GuideText;
+    };
+    steps: GuideStep[];
+}
+/** Shown in place of the welcome while the org is not ready for the tour. */
+export interface GuideGate {
+    /** true: go on; false: show the gate; undefined: still loading. */
+    ready: (ctx: GuideContext) => boolean | undefined;
+    title: string;
+    subtitle?: string;
+    /** The one button, and where it goes (absolute URLs leave the app). */
+    action: {
+        label: string;
+        href: GuideText;
+    };
+    /** The line on each mission in the panel while waiting: "ต้องมีพนักงาน 2 คน". */
+    pending: string;
+}
+/** One app's whole tour: the welcome, the missions, the finish. */
+export interface GuideSuite {
+    /** Progress key on the server, "<app>.<name>": "peoplx.first-run". */
+    key: string;
+    /** Raise it to show the tour again to everyone (resets progress). */
+    version: number;
+    app: GuideAppId;
+    /** The app's name for the phone's menu step: "Peoplx". */
+    appName: string;
+    welcome: {
+        /** "ยินดีต้อนรับ ผู้จัดการ HR" */
+        title: GuideText;
+        /** Default "มาตั้งค่าบริษัทให้พร้อมใน N ภารกิจ". */
+        subtitle?: GuideText;
+    };
+    /**
+     * Pages where the welcome may open by itself (a direct link to an approval
+     * is never interrupted). Default ["/[code]"], the app's home.
+     */
+    welcomeRoutes?: string[];
+    gate?: GuideGate;
+    complete: {
+        /** Default "บริษัทพร้อมใช้งานแล้ว". */
+        title?: GuideText;
+        subtitle?: GuideText;
+        /** "ไปที่ภาพรวม HR" → "/[code]" */
+        action: {
+            label: string;
+            href: GuideText;
+        };
+        /** e.g. "ชวนทีมเข้าใช้งาน" for admins; omitted when it returns no href. */
+        secondary?: {
+            label: string;
+            href: GuideText | ((ctx: GuideContext) => string | undefined);
+        };
+    };
+    missions: GuideMission[];
+}
+/** AppLayoutShell's `guides` prop. */
+export interface GuideConfig {
+    suite: GuideSuite;
+    /** Counts and flags the predicates read. Re-pass when they change. */
+    facts?: GuideFacts;
+    /** Permission check for `requires` (the app's useApiPolicyAccess). */
+    can?: (policyKey: string) => boolean;
+    /**
+     * False holds the tour (e.g. while the plan or the profile loads).
+     * Default true.
+     */
+    ready?: boolean;
+}

package/dist/help/help-button.d.ts

@@ -4,5 +4,9 @@ export interface HelpButtonProps {
 /**
  * The ช่วยเหลือ button in the top bar. Drawn in the header's ink (the
  * --header-* variables of the workspace chrome, white on the brand chrome).
+ *
+ * When this user has a guided tour in this app, it opens a small menu:
+ * "ไกด์เริ่มต้น n/N" (the quest panel) and "ติดต่อทีมช่วยเหลือ" (the help
+ * dialog). Otherwise one press opens the help dialog, as before.
  */
 export declare function HelpButton({ className }: HelpButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export { NavUser, type NavUserProps, type NavUserSystemLink } from "./navigation
 export { useMyRoles, myRolesQueryKey } from "./navigation/use-my-roles";
 export { parseMyRoles, roleSummary, OWNER_CHIP, type MyRole, type MyRoles, } from "./navigation/my-roles";
 export { buildSystemLinks, type BuildSystemLinksOptions, type ErpAppId, } from "./navigation/app-registry";
+export { accountSettingsHref, platformBaseUrl, type AccountSettingsHrefOptions, } from "./navigation/platform-url";
 export { PLAN_FEATURES, hasPlanFeature, type PlanFeatureKey, } from "./lib/plan-features";
 export { NavMain, type NavMainProps } from "./navigation/nav-main";
 export { OrganizationSwitcher, type OrganizationSwitcherProps, type OrganizationLike, } from "./navigation/organization-switcher";
@@ -32,6 +33,10 @@ 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 { GuideAnchorKey, GuideApiFailure, GuideApiMatch, GuideAppId, GuideCaptureEvent, GuideConfig, GuideContext, GuideFacts, GuideGate, GuideMission, 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";
 export { AccessDenied, type AccessDeniedProps } from "./auth/access-denied";
 export { EmployeeRequiredGate, EMPLOYEE_RECORD_REQUIRED, EMPLOYEE_RECORD_REQUIRED_EVENT, EMPLOYEE_RECORD_OK_EVENT, } from "./auth/employee-required-gate";
 export { PermissionGateShell, type PermissionGateShellProps, type PermissionGateSkeletonVariant, } from "./auth/permission-gate-shell";