@rightkit/onboarding 0.2.0 → 0.2.1

package/README.md

@@ -27,7 +27,39 @@ import "@rightkit/onboarding/onboarding.css";
 | `modelsIntro` | App copy shown at the top of the models step. |
 | `allowSkip` | Show "Set up later" (default `true`). |
 | `titlebar` | Node rendered in a strip along the top. |
-| `dragRegion` | Add `data-tauri-drag-region` to that strip (default `false`; height `--rk-onboarding-titlebar-h`, default 32px). |
+| `dragRegion` | Add `data-tauri-drag-region` to that strip on the setup steps (default `false`; height `--rk-onboarding-titlebar-h`, default 32px). Never rendered on the legal stage. |
+| `legalDragRegion` | Also render the drag region on the legal stage (default `false`; the legal gate has no strip, and `titlebar` content alone never adds the attribute). |
+| `legalReceipt` | `{ read(), write(record) }`: the app's own acceptance receipt. See below. |
+
+## App-owned legal receipt
+
+An app that already persists its own acceptance receipt passes `legalReceipt` and keeps that store as the source of truth. `read()` runs on load (sync or async) and returns a `LegalAcceptanceRecord` (`version`, `documentsHash`, `acceptedAt`, `eligibilityBasis`) or `null`. Its result replaces any acceptance in the settings backend: `null`, a throw, or an incomplete record all mean "not accepted", so the gate shows. `requiredVersion` / `isAccepted` then evaluate against the app's receipt, and a receipt for another version re-prompts with `variant: "re-acceptance"`. On agree, `write(record)` is awaited first; if it throws, the gate shows its save-failure alert and nothing else is persisted.
+
+Mapping example for ScrapeRight's four-field `scraperight.legal-acceptance.v1` receipt (`legalAcceptanceVersion`, `legalAcceptedAt`, `legalEligibilityBasis`, `legalMaterialSha256`; pass `documentsHash={LEGAL_MATERIAL_SHA256}` so the hash round-trips):
+
+```ts
+const legalReceipt: LegalReceiptPort = {
+  read() {
+    const r = loadLegalAcceptance(); // reads localStorage "scraperight.legal-acceptance.v1"
+    if (!r?.legalAcceptanceVersion || !r.legalAcceptedAt || !r.legalEligibilityBasis) return null;
+    return {
+      version: r.legalAcceptanceVersion,
+      acceptedAt: r.legalAcceptedAt,
+      eligibilityBasis: r.legalEligibilityBasis, // "individual" | "enterprise"
+      documentsHash: r.legalMaterialSha256 ?? "",
+    };
+  },
+  write(rec) {
+    saveLegalAcceptance({
+      legalAcceptanceVersion: rec.version,
+      legalAcceptedAt: rec.acceptedAt, // UTC ISO, ends in Z
+      legalEligibilityBasis: rec.eligibilityBasis,
+      legalMaterialSha256: rec.documentsHash,
+    });
+  },
+};
+<Onboarding legalReceipt={legalReceipt} requiredVersion={REQUIRED_LEGAL_ACCEPTANCE_VERSION} documentsHash={LEGAL_MATERIAL_SHA256} ... />
+```
 
 ## Custom steps and readiness
 

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): boolean;
 export declare function onboardingStateKey(): string;
-export declare function Onboarding({ settings, legal, steps, permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, modelsIntro, allowSkip, titlebar, dragRegion }: OnboardingProps): import("react").JSX.Element;
+export declare function Onboarding({ settings, legal, steps, permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt }: OnboardingProps): import("react").JSX.Element;

package/dist/Onboarding.js

@@ -31,6 +31,13 @@ function readState(value) {
         ...(legalAcceptance ? { legalAcceptance } : {}),
     };
 }
+/** Replace the acceptance in `state` with the one from the app's receipt (`undefined`: not accepted). */
+function withReceipt(state, record) {
+    const { legalAcceptance: _drop, eligibilityBasis: _basis, ...rest } = state;
+    void _drop;
+    void _basis;
+    return record ? { ...rest, legalAccepted: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record } : { ...rest, legalAccepted: false };
+}
 /** True when the stored acceptance satisfies the host's requirement. */
 export function isLegalAccepted(state, requiredVersion, custom) {
     if (custom)
@@ -66,7 +73,7 @@ function TitleStrip({ titlebar, dragRegion }) {
         return null;
     return _jsx("div", { className: "rk-onboarding__titlebar", "data-testid": "onboarding-titlebar", ...(dragRegion ? { "data-tauri-drag-region": "" } : {}), children: titlebar });
 }
-export function Onboarding({ settings, legal, steps = [], permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, modelsIntro, allowSkip = true, titlebar, dragRegion }) {
+export function Onboarding({ settings, legal, steps = [], permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt }) {
     const [state, setState] = useState(null);
     const [saving, setSaving] = useState(false);
     const [error, setError] = useState(null);
@@ -100,9 +107,34 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
         }
     }, [persist]);
     const saveStep = useCallback(async (patch) => { await save(patch); }, [save]);
-    useEffect(() => { let live = true; void settings.load().then((snapshot) => { if (live)
-        setState(readState(snapshot.values[KEY])); }, (e) => { if (live)
-        setError(e instanceof Error ? e.message : String(e)); }); return () => { live = false; }; }, [settings]);
+    useEffect(() => {
+        let live = true;
+        void (async () => {
+            try {
+                const loaded = readState((await settings.load()).values[KEY]);
+                if (!legalReceipt) {
+                    if (live)
+                        setState(loaded);
+                    return;
+                }
+                // The app's receipt is the source of truth for acceptance; an unreadable receipt counts as none.
+                let record;
+                try {
+                    record = readAcceptance(await legalReceipt.read());
+                }
+                catch {
+                    record = undefined;
+                }
+                if (live)
+                    setState(withReceipt(loaded, record));
+            }
+            catch (e) {
+                if (live)
+                    setError(e instanceof Error ? e.message : String(e));
+            }
+        })();
+        return () => { live = false; };
+    }, [settings, legalReceipt]);
     const builtins = useMemo(() => [
         { id: "legal", label: "Agreement", title: "Review agreement", skippable: false, render: () => _jsx("p", { className: "rk-onboarding__muted", children: "Agreement accepted." }) },
         ...(permissions ? [permissionsStep(permissions)] : []),
@@ -162,10 +194,19 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
         return _jsx("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: _jsx("p", { className: "rk-onboarding__muted", children: "Loading setup\u2026" }) });
     if (needsGate) {
         if (!gateCleared)
-            return _jsxs("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _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: "Loading setup\u2026" })] });
         const reacceptance = activeState.legalAccepted || activeState.legalAcceptance !== undefined;
-        return _jsxs("div", { className: cx("rk-onboarding rk-onboarding--legal", className), "data-testid": "onboarding-legal", "data-variant": reacceptance ? "re-acceptance" : "first-run", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _jsx(LegalGate, { ...legal, variant: reacceptance ? "re-acceptance" : "first-run", onQuit: () => void legal.onQuit?.(), onAgree: async ({ eligibilityBasis }) => {
+        return _jsxs("div", { className: cx("rk-onboarding rk-onboarding--legal", className), "data-testid": "onboarding-legal", "data-variant": reacceptance ? "re-acceptance" : "first-run", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx(LegalGate, { ...legal, variant: reacceptance ? "re-acceptance" : "first-run", onQuit: () => void legal.onQuit?.(), onAgree: async ({ eligibilityBasis }) => {
                         const legalAcceptance = { version: requiredVersion ?? "1", documentsHash: documentsHash ?? await hashDocuments(legal.documents), acceptedAt: new Date().toISOString(), eligibilityBasis };
+                        if (legalReceipt) {
+                            try {
+                                await legalReceipt.write(legalAcceptance);
+                            }
+                            catch (e) {
+                                setError(e instanceof Error ? e.message : String(e));
+                                throw e;
+                            }
+                        }
                         const progress = reacceptance ? {} : { completed: ["legal"], currentStep: builtins.length > 1 ? 1 : 0 };
                         await persist({ legalAccepted: true, eligibilityBasis, legalAcceptance, ...progress });
                         if (!reacceptance && builtins.length === 1)

package/dist/types.d.ts

@@ -66,6 +66,16 @@ export interface LegalAcceptanceRecord {
     acceptedAt: string;
     eligibilityBasis: EligibilityBasis;
 }
+/**
+ * App-owned persistence for the legal acceptance. Lets an app keep its existing receipt (any shape, any store) and map it
+ * to and from the package's record. When supplied it is the source of truth: `read()` is consulted on load and overrides
+ * whatever acceptance the settings backend holds (`null` means "not accepted", so the gate shows), and `write()` is
+ * awaited when the user agrees, before the settings backend is patched.
+ */
+export interface LegalReceiptPort {
+    read(): LegalAcceptanceRecord | null | Promise<LegalAcceptanceRecord | null>;
+    write(record: LegalAcceptanceRecord): void | Promise<void>;
+}
 export interface PersistedOnboardingState {
     version: 1;
     currentStep: number;
@@ -133,7 +143,11 @@ export interface OnboardingProps {
     allowSkip?: boolean;
     /** Optional titlebar content rendered in a strip along the top. */
     titlebar?: ReactNode;
-    /** Render a `data-tauri-drag-region` strip at the top. Default false. */
+    /** Render a `data-tauri-drag-region` strip at the top of the setup steps. Default false. Never applied to the legal stage; see `legalDragRegion`. */
     dragRegion?: boolean;
+    /** Also render the drag region on the legal stage (loading and gate). Default false: the legal gate has no strip. */
+    legalDragRegion?: boolean;
+    /** Read and write the legal acceptance in the app's own receipt instead of (overriding) the settings backend's copy. */
+    legalReceipt?: LegalReceiptPort;
 }
 export type { LegalGateDocument, LegalGateTheme };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",
@@ -30,7 +30,7 @@
   },
   "devDependencies": {
     "@rightkit/app-shell": "0.2.0",
-    "@rightkit/legal-ui": "0.1.2",
+    "@rightkit/legal-ui": "0.1.3",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",