@rightkit/onboarding 0.6.0 → 0.6.2

package/README.md

@@ -49,7 +49,7 @@ Acceptance is stored as `legalAcceptance: { version, documentsHash, acceptedAt,
 
 ## When the legal gate re-prompts
 
-`isLegalAccepted(state, requiredVersion?, isAccepted?, requiredDocumentsHash?)` decides it, in this order: a custom `isAccepted` wins outright; a `requiredDocumentsHash` must equal the stored acceptance's `documentsHash`; a `requiredVersion` must equal its `version`; with neither, the stored `legalAccepted` flag is used. Pass `requiredDocumentsHash` (the hash of the material documents, from `@rightkit/legal`) to catch a text change that did not bump the version: without it only the version is compared. `documentsHash` is recorded with the acceptance and never compared; by default it covers document titles and URLs, not their text.
+`isLegalAccepted(state, requiredVersion?, isAccepted?, requiredDocumentsHash?)` decides it, in this order: a custom `isAccepted` wins outright; a `requiredDocumentsHash` must equal the stored acceptance's `documentsHash`; a `requiredVersion` must equal its `version`; with neither, a recorded acceptance (`legalAcceptance`) is still required, so a bare legacy `legalAccepted` flag re-prompts once as a re-acceptance. Pass `requiredDocumentsHash` (the hash of the material documents, from `@rightkit/legal`) to catch a text change that did not bump the version: without it only the version is compared. `documentsHash` is recorded with the acceptance and never compared; by default it covers document titles and URLs, not their text.
 
 ## Known issues
 

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, labels: labelOverrides }: OnboardingProps): import("react").JSX.Element | null;
+export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, onComplete, onSkip, className, layout, 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

@@ -7,11 +7,22 @@ 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…" };
+/** Same canonical-UTC rule as `@rightkit/legal` receipts: `Date#toISOString()` form, round-tripping unchanged. */
+function isCanonicalUtc(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value))
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
 function readAcceptance(value) {
-    if (!value || typeof value !== "object")
+    if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
     const r = value;
-    if (typeof r.version !== "string" || typeof r.documentsHash !== "string" || typeof r.acceptedAt !== "string")
+    if (typeof r.version !== "string" || !r.version.trim())
+        return undefined;
+    if (typeof r.documentsHash !== "string" || !r.documentsHash.trim())
+        return undefined;
+    if (!isCanonicalUtc(r.acceptedAt))
         return undefined;
     if (r.eligibilityBasis !== "individual" && r.eligibilityBasis !== "enterprise")
         return undefined;
@@ -22,12 +33,15 @@ function readState(value) {
         return INITIAL;
     const candidate = value;
     const legalAcceptance = readAcceptance(candidate.legalAcceptance);
+    // A present receipt is authoritative, including when it is malformed. Keep the
+    // legacy boolean only for state written before the receipt field existed.
+    const hasStoredAcceptance = Object.prototype.hasOwnProperty.call(candidate, "legalAcceptance");
     return {
         version: 1,
         currentStep: typeof candidate.currentStep === "number" && candidate.currentStep >= 0 ? Math.floor(candidate.currentStep) : 0,
         completed: Array.isArray(candidate.completed) ? candidate.completed.filter((x) => typeof x === "string") : [],
         skipped: candidate.skipped === true,
-        legalAccepted: candidate.legalAccepted === true || legalAcceptance !== undefined,
+        legalAccepted: legalAcceptance !== undefined || (!hasStoredAcceptance && candidate.legalAccepted === true),
         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") } : {}),
@@ -44,15 +58,19 @@ function withReceipt(state, record) {
 export function isLegalAccepted(state, requiredVersion, custom, requiredDocumentsHash) {
     if (custom)
         return custom(state);
+    // A stored record whose timestamp is not canonical UTC is not an acceptance,
+    // even when the host passes no version/hash requirement (same rule as legal receipts).
+    if (state.legalAcceptance !== undefined && !isCanonicalUtc(state.legalAcceptance.acceptedAt))
+        return false;
     // A host that supplies the documents' hash is asking for the text itself to be what was accepted:
     // a changed text re-prompts even when the version string did not move.
     if (requiredDocumentsHash !== undefined && state.legalAcceptance?.documentsHash !== requiredDocumentsHash)
         return false;
     if (requiredVersion !== undefined)
         return state.legalAcceptance?.version === requiredVersion;
-    if (requiredDocumentsHash !== undefined)
-        return state.legalAcceptance !== undefined;
-    return state.legalAccepted;
+    // With no version or hash requirement a recorded acceptance is still required: a bare legacy
+    // `legalAccepted` flag carries no version, time or basis, so it re-prompts once (as re-acceptance).
+    return state.legalAcceptance !== undefined;
 }
 /** FNV-1a fallback when SubtleCrypto is unavailable. */
 function fnv(text) {
@@ -86,7 +104,7 @@ 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, labels: labelOverrides }) {
+export function Onboarding({ settings, legal, legalMode = "gate", appName, steps = [], permissions, models, license, onComplete, onSkip, className, layout = "window", 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 };
@@ -248,19 +266,20 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
         }
         await markAndMove(index + 1, { completed: active.id });
     };
+    const rootClass = cx("rk-onboarding", layout === "contained" && "rk-onboarding--contained", className);
     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" })] });
+        return _jsxs("div", { className: rootClass, 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(resultOf(activeState.completed, activeState.skippedSteps ?? []))), children: L.finish })] });
+        return _jsxs("main", { className: rootClass, "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: L.loading }) });
+        return _jsx("div", { className: rootClass, "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: L.loading })] });
+            return _jsxs("div", { className: rootClass, "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;
-        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 }) => {
+        return _jsxs("div", { className: cx("rk-onboarding rk-onboarding--legal", layout === "contained" && "rk-onboarding--contained", className), "data-testid": "onboarding-legal", "data-variant": reacceptance ? "re-acceptance" : "first-run", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx(LegalGate, { ...legal, layout: layout, variant: reacceptance ? "re-acceptance" : "first-run", onQuit: () => void legal.onQuit?.(), onAgree: async ({ eligibilityBasis }) => {
                         const legalAcceptance = { version: requiredVersion ?? "1", documentsHash: documentsHash ?? requiredDocumentsHash ?? await hashDocuments(legal.documents), acceptedAt: new Date().toISOString(), eligibilityBasis };
                         if (legalReceipt) {
                             try {
@@ -278,6 +297,6 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
                     } })] });
     }
     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) || continuing, onClick: () => { if (!continuing && i >= lead && (i <= index || canContinue))
+    return _jsxs("main", { className: rootClass, "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/types.d.ts

@@ -178,6 +178,8 @@ export interface LegalStepConfig extends Omit<LegalGateProps, "variant" | "onAgr
  */
 export type LegalMode = "gate" | "notice" | "none";
 export interface OnboardingProps {
+    /** Window-sized by default; use `contained` when the host sizes the setup surface. */
+    layout?: "window" | "contained";
     settings: SettingsBackend;
     /** Required when `legalMode` is `gate` (default). Optional for `notice` (the documents shown) and `none`. */
     legal?: LegalStepConfig;

package/onboarding.css

@@ -1,5 +1,6 @@
 /* @rightkit/onboarding — uses app-shell tokens and legal-ui's locked light gate. */
 .rk-onboarding { position: relative; min-height: 100vh; display: grid; grid-template-columns: 220px minmax(0, 1fr); background: var(--rk-plane, #fffcf5); color: var(--rk-ink, #231f1a); font: 13px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; }
+.rk-onboarding--contained { min-height: 0; }
 .rk-onboarding *, .rk-onboarding *::before, .rk-onboarding *::after { box-sizing: border-box; }
 .rk-onboarding__rail { display: flex; flex-direction: column; gap: 22px; padding: 28px 14px; background: var(--rk-chrome, #eee9df); border-right: .5px solid var(--rk-hairline, rgba(35,31,26,.11)); }
 .rk-onboarding__brand { padding: 0 10px; font-size: 19px; font-weight: 650; letter-spacing: -.02em; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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",
@@ -25,12 +25,12 @@
   ],
   "peerDependencies": {
     "@rightkit/react-shell": ">=0.2.0 <1",
-    "@rightkit/legal-ui": ">=0.1.2 <1",
+    "@rightkit/legal-ui": ">=0.4.1 <1",
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/react-shell": "0.7.0",
-    "@rightkit/legal-ui": "0.4.0",
+    "@rightkit/react-shell": "0.7.1",
+    "@rightkit/legal-ui": "0.4.1",
     "@rightkit/qa-chrome": "0.1.8",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/dom": "^10.4.2",