@rightkit/onboarding 0.5.0 → 0.6.0

package/README.md

@@ -13,7 +13,7 @@ First-run onboarding framework for Right Suite apps. The legal agreement gate co
 
 | Import | Contents |
 |---|---|
-| `@rightkit/onboarding` | `Onboarding`, `isLegalAccepted`, `onboardingStateKey`, `licenseStep`, `modelsStep`, `permissionsStep`, `signInStep` (Google/Apple/OAuth buttons that call the shared `rightkit-oauth` owner; copy says "Opens your browser"; never an in-app webview, Orthic-Labs/rightkit#279); types from `types.ts`, `ModelsStepOptions` |
+| `@rightkit/onboarding` | `Onboarding`, `isLegalAccepted`, `onboardingStateKey`, `licenseStep`, `modelsStep`, `permissionsStep`, `signInStep` (Google/Apple/OAuth buttons that call the shared `rightkit-oauth` owner; copy says "Opens your browser"; never an in-app webview, bogusyogi/rightkit#279); types from `types.ts`, `ModelsStepOptions` |
 | `@rightkit/onboarding/onboarding.css` | Stylesheet |
 
 ## Peer dependencies
@@ -45,7 +45,7 @@ import "@rightkit/onboarding/onboarding.css";
 
 Free or open-source apps without a legal gate pass `legalMode="none"` (no legal step, `legal` not needed, `appName` for the rail) or `legalMode="notice"` (no gate or acceptance; a first Notice step lists `legal.documents` as links). The default is `"gate"`.
 
-Acceptance is stored as `legalAcceptance: { version, documentsHash, acceptedAt, eligibilityBasis }`. An app that already keeps its own acceptance receipt can pass `legalReceipt` (`read()` and `write(record)`) and keep that store as the source of truth. Steps can set `canContinue(context)`.
+Acceptance is stored as `legalAcceptance: { version, documentsHash, acceptedAt, eligibilityBasis }`. An app that already keeps its own acceptance receipt can pass `legalReceipt` (`read()` and `write(record)`) and keep that store as the source of truth. Steps can set `canContinue(context)`, `onContinue(context)` (a veto: `false` or a throw keeps the step), `continueLabel`, and `skippable` (a per-step Skip button). `ctx.setResult(value)` stores a value that `onComplete({ completed, skipped, steps })` receives. `labels` overrides the button and status text, and `licenseStep(backend, { copy })` overrides the licence copy.
 
 ## When the legal gate re-prompts
 

package/dist/Onboarding.d.ts

@@ -2,4 +2,4 @@ import type { OnboardingProps, PersistedOnboardingState } from "./types.js";
 /** True when the stored acceptance satisfies the host's requirement. */
 export declare function isLegalAccepted(state: PersistedOnboardingState, requiredVersion?: string, custom?: (state: PersistedOnboardingState) => boolean, requiredDocumentsHash?: string): boolean;
 export declare function onboardingStateKey(): string;
-export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, onComplete, onSkip, className, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt }: OnboardingProps): import("react").JSX.Element | null;
+export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, onComplete, onSkip, className, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt, labels: labelOverrides }: OnboardingProps): import("react").JSX.Element | null;

package/dist/Onboarding.js

@@ -6,6 +6,7 @@ import { cx } from "./ui.js";
 import { licenseStep, modelsStep, permissionsStep } from "./steps.js";
 const KEY = "onboarding.state";
 const INITIAL = { version: 1, currentStep: 0, completed: [], skipped: false, legalAccepted: false };
+const DEFAULT_LABELS = { skip: "Set up later", skipStep: "Skip", back: "Back", continue: "Continue", finish: "Finish setup", loading: "Loading setup…" };
 function readAcceptance(value) {
     if (!value || typeof value !== "object")
         return undefined;
@@ -29,6 +30,7 @@ function readState(value) {
         legalAccepted: candidate.legalAccepted === true || legalAcceptance !== undefined,
         eligibilityBasis: legalAcceptance?.eligibilityBasis ?? (candidate.eligibilityBasis === "individual" || candidate.eligibilityBasis === "enterprise" ? candidate.eligibilityBasis : undefined),
         ...(legalAcceptance ? { legalAcceptance } : {}),
+        ...(Array.isArray(candidate.skippedSteps) ? { skippedSteps: candidate.skippedSteps.filter((x) => typeof x === "string") } : {}),
     };
 }
 /** Replace the acceptance in `state` with the one from the app's receipt (`undefined`: not accepted). */
@@ -84,9 +86,10 @@ function NoticeList({ documents }) {
         return _jsx("p", { className: "rk-onboarding__muted", children: "No notices to show." });
     return _jsx("ul", { className: "rk-onboarding__notices", children: documents.map((d) => _jsx("li", { children: d.onOpen ? _jsx("button", { type: "button", onClick: d.onOpen, children: d.title }) : d.url ? _jsx("a", { href: d.url, target: "_blank", rel: "noreferrer", children: d.title }) : d.title }, d.title)) });
 }
-export function Onboarding({ settings, legal, legalMode = "gate", appName, steps = [], permissions, models, license, onComplete, onSkip, className, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt }) {
+export function Onboarding({ settings, legal, legalMode = "gate", appName, steps = [], permissions, models, license, onComplete, onSkip, className, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt, labels: labelOverrides }) {
     if (legalMode === "gate" && !legal)
         throw new Error("Onboarding: `legal` is required when legalMode is \"gate\"");
+    const L = { ...DEFAULT_LABELS, ...labelOverrides };
     const gated = legalMode === "gate";
     /** Leading steps the user cannot navigate to: the Agreement stand-in in gate mode. */
     const lead = gated ? 1 : 0;
@@ -97,6 +100,9 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
     const [gateCleared, setGateCleared] = useState(false);
     /** One auto-start per mount, even when the models step unmounts (Back/Next) or the step list is rebuilt. */
     const modelsStarted = useRef(false);
+    /** Values passed to `ctx.setResult`, keyed by step id; handed to `onComplete`. */
+    const stepResults = useRef({});
+    const [continuing, setContinuing] = useState(false);
     /** Persists a patch; throws when the settings backend rejects it. */
     const persist = useCallback(async (patch) => {
         setSaving(true);
@@ -169,6 +175,9 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
     const index = !accepted ? 0 : builtins.length > lead ? Math.max(lead, Math.min(activeState.currentStep, builtins.length - 1)) : 0;
     const active = builtins[index];
     const activeId = active?.id ?? "";
+    /** The step on screen now; an `onContinue` that resolves after the step changed is stale. */
+    const activeIdRef = useRef(activeId);
+    activeIdRef.current = activeId;
     const setReady = useCallback((ready) => setReadyMap((m) => m[activeId] === ready ? m : { ...m, [activeId]: ready }), [activeId]);
     useEffect(() => {
         if (!needsGate) {
@@ -188,7 +197,8 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
             setGateCleared(true); })();
         return () => { live = false; };
     }, [needsGate, gateCleared, beforeLegalGate]);
-    const context = { state: activeState, settings, setState: saveStep, permissions, models, license, ready: readyMap, setReady };
+    const setResult = useCallback((value) => { stepResults.current[activeId] = value; }, [activeId]);
+    const context = { state: activeState, settings, setState: saveStep, permissions, models, license, ready: readyMap, setReady, setResult };
     const canContinue = active?.canContinue ? active.canContinue(context) : true;
     const runCallback = async (callback) => {
         try {
@@ -198,24 +208,55 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
             setError(e instanceof Error ? e.message : String(e));
         }
     };
-    const markAndMove = async (nextIndex, completedId) => {
-        const completed = completedId && !activeState.completed.includes(completedId) ? [...activeState.completed, completedId] : activeState.completed;
+    const resultOf = (completed, skipped) => ({ completed, skipped, steps: { ...stepResults.current } });
+    /** Marks `mark.completed` done or `mark.skipped` skipped (never both), then moves to `nextIndex`; completing the last step calls `onComplete`. */
+    const markAndMove = async (nextIndex, mark = {}) => {
+        const previousSkipped = activeState.skippedSteps ?? [];
+        // A step is completed or skipped, never both: a skip removes an earlier completion of the same step.
+        const completedBase = activeState.completed.filter((id) => id !== mark.skipped);
+        const completed = mark.completed && !completedBase.includes(mark.completed) ? [...completedBase, mark.completed] : completedBase;
+        const skippedBase = previousSkipped.filter((id) => id !== mark.completed);
+        const skippedSteps = mark.skipped && !skippedBase.includes(mark.skipped) ? [...skippedBase, mark.skipped] : skippedBase;
         if (nextIndex >= builtins.length) {
-            if (await save({ completed, currentStep: Math.max(0, builtins.length - 1), skipped: false }))
-                await runCallback(onComplete);
+            if (await save({ completed, skippedSteps, currentStep: Math.max(0, builtins.length - 1), skipped: false }))
+                await runCallback(() => onComplete(resultOf(completed, skippedSteps)));
             return;
         }
-        await save({ completed, currentStep: nextIndex, skipped: false });
+        await save({ completed, skippedSteps, currentStep: nextIndex, skipped: false });
+    };
+    /** Primary button: runs the step's `onContinue` veto first; `false` or a throw keeps the step. */
+    const advance = async () => {
+        if (active.onContinue) {
+            const stepId = active.id;
+            setContinuing(true);
+            setError(null);
+            let proceed = true;
+            try {
+                proceed = (await active.onContinue(context)) !== false;
+            }
+            catch (e) {
+                if (activeIdRef.current === stepId)
+                    setError(e instanceof Error ? e.message : String(e));
+                return;
+            }
+            finally {
+                setContinuing(false);
+            }
+            // The step changed while onContinue was awaited: discard this completion rather than move or save from stale state.
+            if (!proceed || activeIdRef.current !== stepId)
+                return;
+        }
+        await markAndMove(index + 1, { completed: active.id });
     };
     if (error && !state)
         return _jsxs("div", { className: cx("rk-onboarding", className), children: [_jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }), _jsx(Button, { onClick: () => window.location.reload(), children: "Retry" })] });
     if (state && !active)
-        return _jsxs("main", { className: cx("rk-onboarding", className), "data-testid": "onboarding", children: [_jsx("p", { className: "rk-onboarding__muted", children: "Nothing to set up." }), _jsx(Button, { variant: "primary", onClick: () => void runCallback(onComplete), children: "Finish setup" })] });
+        return _jsxs("main", { className: cx("rk-onboarding", className), "data-testid": "onboarding", children: [_jsx("p", { className: "rk-onboarding__muted", children: "Nothing to set up." }), _jsx(Button, { variant: "primary", onClick: () => void runCallback(() => onComplete(resultOf(activeState.completed, activeState.skippedSteps ?? []))), children: L.finish })] });
     if (!state || !active)
-        return _jsx("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: _jsx("p", { className: "rk-onboarding__muted", children: "Loading setup\u2026" }) });
+        return _jsx("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: _jsx("p", { className: "rk-onboarding__muted", children: L.loading }) });
     if (needsGate) {
         if (!gateCleared)
-            return _jsxs("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx("p", { className: "rk-onboarding__muted", children: "Loading setup\u2026" })] });
+            return _jsxs("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx("p", { className: "rk-onboarding__muted", children: L.loading })] });
         if (!legal)
             return null;
         const reacceptance = activeState.legalAccepted || activeState.legalAcceptance !== undefined;
@@ -233,10 +274,10 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
                         const progress = reacceptance ? {} : { completed: ["legal"], currentStep: builtins.length > 1 ? 1 : 0 };
                         await persist({ legalAccepted: true, eligibilityBasis, legalAcceptance, ...progress });
                         if (!reacceptance && builtins.length === 1)
-                            await onComplete();
+                            await onComplete(resultOf(["legal"], []));
                     } })] });
     }
     const body = active.render(context);
-    return _jsxs("main", { className: cx("rk-onboarding", className), "data-testid": "onboarding", "data-step-id": active.id, children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _jsxs("aside", { className: "rk-onboarding__rail", children: [_jsx("div", { className: "rk-onboarding__brand", children: appName ?? legal?.appName }), _jsx("nav", { "aria-label": "Setup progress", children: builtins.map((step, i) => _jsxs("button", { type: "button", className: cx("rk-onboarding__step", i === index && "is-active", activeState.completed.includes(step.id) && "is-done"), "aria-current": i === index ? "step" : undefined, disabled: gated && i === 0 && builtins.length > 1, onClick: () => { if (i >= lead && (i <= index || canContinue))
-                                void save({ currentStep: i }); }, children: [_jsx("span", { children: activeState.completed.includes(step.id) ? "✓" : i + 1 }), step.label] }, step.id)) })] }), _jsxs("section", { className: "rk-onboarding__main", children: [_jsxs("header", { children: [_jsxs("p", { className: "rk-onboarding__eyebrow", children: ["Step ", index + 1, " of ", builtins.length] }), _jsx("h1", { children: active.title }), active.description ? _jsx("p", { className: "rk-onboarding__description", children: active.description }) : null] }), _jsx("div", { className: "rk-onboarding__content", children: body }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, _jsxs("footer", { children: [allowSkip ? _jsx(Button, { variant: "ghost", disabled: saving, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: "Set up later" }) : null, _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), _jsx(Button, { variant: "secondary", disabled: index <= lead || saving, onClick: () => void save({ currentStep: index - 1 }), children: "Back" }), _jsx(Button, { variant: "primary", disabled: saving || !canContinue, onClick: () => void markAndMove(index + 1, active.id), children: index === builtins.length - 1 ? "Finish setup" : "Continue" })] })] })] });
+    return _jsxs("main", { className: cx("rk-onboarding", className), "data-testid": "onboarding", "data-step-id": active.id, children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _jsxs("aside", { className: "rk-onboarding__rail", children: [_jsx("div", { className: "rk-onboarding__brand", children: appName ?? legal?.appName }), _jsx("nav", { "aria-label": "Setup progress", children: builtins.map((step, i) => _jsxs("button", { type: "button", className: cx("rk-onboarding__step", i === index && "is-active", activeState.completed.includes(step.id) && "is-done"), "aria-current": i === index ? "step" : undefined, disabled: (gated && i === 0 && builtins.length > 1) || continuing, onClick: () => { if (!continuing && i >= lead && (i <= index || canContinue))
+                                void save({ currentStep: i }); }, children: [_jsx("span", { children: activeState.completed.includes(step.id) ? "✓" : i + 1 }), step.label] }, step.id)) })] }), _jsxs("section", { className: "rk-onboarding__main", children: [_jsxs("header", { children: [_jsxs("p", { className: "rk-onboarding__eyebrow", children: ["Step ", index + 1, " of ", builtins.length] }), active.title ? _jsx("h1", { children: active.title }) : null, active.description ? _jsx("p", { className: "rk-onboarding__description", children: active.description }) : null] }), _jsx("div", { className: "rk-onboarding__content", children: body }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, _jsxs("footer", { children: [allowSkip ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: L.skip }) : null, active.skippable ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => void markAndMove(index + 1, { skipped: active.id }), children: L.skipStep }) : null, _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), _jsx(Button, { variant: "secondary", disabled: index <= lead || saving || continuing, onClick: () => void save({ currentStep: index - 1 }), children: L.back }), _jsx(Button, { variant: "primary", disabled: saving || continuing || !canContinue, onClick: () => void advance(), children: active.continueLabel ?? (index === builtins.length - 1 ? L.finish : L.continue) })] })] })] });
 }

package/dist/steps.d.ts

@@ -21,11 +21,26 @@ export interface ModelsStepOptions extends ModelsAutoStart {
     };
 }
 export declare function modelsStep(backend: ModelsBackend, options?: ModelsStepOptions): OnboardingStep;
-export declare function licenseStep(backend: LicenseBackend, options?: {
+/** Copy overrides for the licence step. Each key defaults to the English text. */
+export interface LicenseStepCopy {
+    /** Key field label and placeholder. Default "Licence key". */
+    keyLabel?: string;
+    /** Submit button. Default "Activate". */
+    activateLabel?: string;
+    /** Trial button. Default "Start trial". */
+    trialLabel?: string;
+    /** Plans link. Default "View plans". */
+    plansLabel?: string;
+    /** Status text when no licence is active. Default "You can continue without a licence.". */
+    noLicenceDetail?: string;
+}
+export interface LicenseStepOptions {
     label?: string;
     title?: string;
     description?: string;
-}): OnboardingStep;
+    copy?: LicenseStepCopy;
+}
+export declare function licenseStep(backend: LicenseBackend, options?: LicenseStepOptions): OnboardingStep;
 /** Sign-in step. Every button hands off to the shared owner and opens the user's default browser; no in-app webview. */
 export declare function signInStep(backend: SignInBackend, options?: {
     label?: string;

package/dist/steps.js

@@ -100,18 +100,22 @@ export function modelsStep(backend, options = {}) {
         render: (ctx) => _jsx(ModelsBody, { backend: backend, onReady: ctx.setReady, autoStartDownload: options.autoStartDownload, shouldAutoStart: options.shouldAutoStart, onModelsStepEnter: options.onModelsStepEnter, intro: options.intro, startGuard: options.startGuard }),
     };
 }
-function LicenseBody({ backend }) {
+function LicenseBody({ backend, copy }) {
     const [state, setState] = useState({ status: "none" });
     const [key, setKey] = useState("");
     const [busy, setBusy] = useState(false);
     const [error, setError] = useState(null);
     useEffect(() => void backend.load().then(setState, (e) => setError(e instanceof Error ? e.message : String(e))), [backend]);
     const run = (fn) => { setBusy(true); setError(null); void fn().then(setState, (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(false)); };
-    return _jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-license", children: [_jsxs("div", { className: "rk-onboarding__license-state", children: [_jsx(Badge, { tone: state.status === "active" || state.status === "trial" ? "ok" : state.status === "expired" || state.status === "invalid" ? "bad" : "neutral", children: state.label ?? state.status }), _jsx("span", { children: state.detail ?? "You can continue without a licence." })] }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, backend.activate ? _jsxs("form", { className: "rk-onboarding__form", onSubmit: (e) => { e.preventDefault(); if (key.trim())
-                    run(() => backend.activate(key.trim())); }, children: [_jsx(Input, { "aria-label": "Licence key", placeholder: "Licence key", value: key, onChange: (e) => setKey(e.target.value), disabled: busy }), _jsx(Button, { size: "sm", variant: "primary", type: "submit", disabled: busy || !key.trim(), children: "Activate" })] }) : null, _jsxs("div", { className: "rk-onboarding__row-actions", children: [backend.startTrial ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy, onClick: () => run(() => backend.startTrial()), children: "Start trial" }) : null, backend.purchaseUrl ? _jsx(Button, { size: "sm", variant: "ghost", onClick: () => void backend.openExternal?.(backend.purchaseUrl), children: "View plans" }) : null] })] });
+    return _jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-license", children: [_jsxs("div", { className: "rk-onboarding__license-state", children: [_jsx(Badge, { tone: state.status === "active" || state.status === "trial" ? "ok" : state.status === "expired" || state.status === "invalid" ? "bad" : "neutral", children: state.label ?? state.status }), _jsx("span", { children: state.detail ?? copy.noLicenceDetail })] }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, backend.activate ? _jsxs("form", { className: "rk-onboarding__form", onSubmit: (e) => { e.preventDefault(); if (key.trim())
+                    run(() => backend.activate(key.trim())); }, children: [_jsx(Input, { "aria-label": copy.keyLabel, placeholder: copy.keyLabel, value: key, onChange: (e) => setKey(e.target.value), disabled: busy }), _jsx(Button, { size: "sm", variant: "primary", type: "submit", disabled: busy || !key.trim(), children: copy.activateLabel })] }) : null, _jsxs("div", { className: "rk-onboarding__row-actions", children: [backend.startTrial ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy, onClick: () => run(() => backend.startTrial()), children: copy.trialLabel }) : null, backend.purchaseUrl ? _jsx(Button, { size: "sm", variant: "ghost", onClick: () => void backend.openExternal?.(backend.purchaseUrl), children: copy.plansLabel }) : null] })] });
 }
 export function licenseStep(backend, options = {}) {
-    return { id: "license", label: options.label ?? "Licence", title: options.title ?? "Choose how you’ll use this app", description: options.description ?? "Activate a licence, start a trial, or continue with the free plan.", skippable: true, render: () => _jsx(LicenseBody, { backend: backend }) };
+    const copy = {
+        keyLabel: "Licence key", activateLabel: "Activate", trialLabel: "Start trial", plansLabel: "View plans",
+        noLicenceDetail: "You can continue without a licence.", ...options.copy,
+    };
+    return { id: "license", label: options.label ?? "Licence", title: options.title ?? "Choose how you’ll use this app", description: options.description ?? "Activate a licence, start a trial, or continue with the free plan.", skippable: true, render: () => _jsx(LicenseBody, { backend: backend, copy: copy }) };
 }
 function SignInBody({ backend }) {
     const [account, setAccount] = useState({ signedIn: false });

package/dist/types.d.ts

@@ -108,6 +108,29 @@ export interface PersistedOnboardingState {
     /** Legacy mirror of `legalAcceptance.eligibilityBasis`. */
     eligibilityBasis?: EligibilityBasis;
     legalAcceptance?: LegalAcceptanceRecord;
+    /** Step ids the user skipped with the per-step Skip button (not marked complete). */
+    skippedSteps?: string[];
+}
+/** What `onComplete` receives. `steps` holds values passed to `ctx.setResult` during this mount. */
+export interface OnboardingResult {
+    completed: string[];
+    skipped: string[];
+    steps: Record<string, unknown>;
+}
+/** Button and status copy. Each key defaults to the English text shown in the table. */
+export interface OnboardingLabels {
+    /** "Set up later". */
+    skip: string;
+    /** Per-step Skip button. */
+    skipStep: string;
+    /** "Back". */
+    back: string;
+    /** "Continue". */
+    continue: string;
+    /** "Finish setup" on the last step. */
+    finish: string;
+    /** "Loading setup…". */
+    loading: string;
 }
 export interface OnboardingStepContext {
     state: PersistedOnboardingState;
@@ -121,6 +144,8 @@ export interface OnboardingStepContext {
     ready: Readonly<Record<string, boolean>>;
     /** Reports whether the active step is ready (used by `canContinue`). Stable per step. */
     setReady: (ready: boolean) => void;
+    /** Stores a value for this step; it is passed to `onComplete` as `result.steps[step.id]`. */
+    setResult: (value: unknown) => void;
 }
 export interface OnboardingStep {
     id: string;
@@ -132,6 +157,14 @@ export interface OnboardingStep {
     canContinue?: (context: OnboardingStepContext) => boolean;
     /** Shown beside the disabled Continue/Finish button. */
     blockedHint?: string;
+    /** Primary button text for this step (e.g. "Open CodeRight"). Overrides Continue and Finish setup. */
+    continueLabel?: string;
+    /**
+     * Runs before Continue/Finish advances. Return `false` (or throw) to keep the step; a throw shows its message.
+     * `void` or `true` advances. Not run for Back, the rail, or Skip.
+     */
+    onContinue?: (context: OnboardingStepContext) => void | boolean | Promise<void | boolean>;
+    /** Empty title hides the heading (e.g. a Welcome step). */
     render: (context: OnboardingStepContext) => ReactNode;
 }
 export interface LegalStepConfig extends Omit<LegalGateProps, "variant" | "onAgree" | "onQuit"> {
@@ -157,8 +190,11 @@ export interface OnboardingProps {
     permissions?: PermissionsBackend;
     models?: ModelsBackend;
     license?: LicenseBackend;
-    onComplete: () => void | Promise<void>;
+    /** Called once when setup finishes, with the completed and skipped step ids and the step results. */
+    onComplete: (result: OnboardingResult) => void | Promise<void>;
     onSkip?: () => void | Promise<void>;
+    /** Override any button or status text. Keys not given keep the English defaults. */
+    labels?: Partial<OnboardingLabels>;
     className?: string;
     /** Version the user must have accepted. A different (or missing) stored version re-prompts with `variant: "re-acceptance"`. */
     requiredVersion?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "First-run onboarding framework: ordered steps, progress, skip/resume, legal gate first, permissions, model download and licence/trial steps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/react-shell": "0.6.8",
-    "@rightkit/legal-ui": "0.3.0",
+    "@rightkit/react-shell": "0.7.0",
+    "@rightkit/legal-ui": "0.4.0",
     "@rightkit/qa-chrome": "0.1.8",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/dom": "^10.4.2",
@@ -51,7 +51,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Orthic-Labs/rightkit.git",
+    "url": "git+https://github.com/bogusyogi/rightkit.git",
     "directory": "packages/onboarding"
   },
   "scripts": {