@unisim/assess-kit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +223 -0
  2. package/dist/evidence.d.ts +102 -0
  3. package/dist/evidence.d.ts.map +1 -0
  4. package/dist/evidence.js +241 -0
  5. package/dist/evidence.js.map +1 -0
  6. package/dist/export-gate.d.ts +184 -0
  7. package/dist/export-gate.d.ts.map +1 -0
  8. package/dist/export-gate.js +320 -0
  9. package/dist/export-gate.js.map +1 -0
  10. package/dist/hub.d.ts +67 -0
  11. package/dist/hub.d.ts.map +1 -0
  12. package/dist/hub.js +60 -0
  13. package/dist/hub.js.map +1 -0
  14. package/dist/index.d.ts +8 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +10 -0
  17. package/dist/index.js.map +1 -0
  18. package/dist/pdf-fold.d.ts +20 -0
  19. package/dist/pdf-fold.d.ts.map +1 -0
  20. package/dist/pdf-fold.js +51 -0
  21. package/dist/pdf-fold.js.map +1 -0
  22. package/dist/pdf-fonts.d.ts +49 -0
  23. package/dist/pdf-fonts.d.ts.map +1 -0
  24. package/dist/pdf-fonts.js +84 -0
  25. package/dist/pdf-fonts.js.map +1 -0
  26. package/dist/platform.d.ts +14 -0
  27. package/dist/platform.d.ts.map +1 -0
  28. package/dist/platform.js +30 -0
  29. package/dist/platform.js.map +1 -0
  30. package/dist/react/evidence.d.ts +78 -0
  31. package/dist/react/evidence.d.ts.map +1 -0
  32. package/dist/react/evidence.js +148 -0
  33. package/dist/react/evidence.js.map +1 -0
  34. package/dist/react/index.d.ts +4 -0
  35. package/dist/react/index.d.ts.map +1 -0
  36. package/dist/react/index.js +6 -0
  37. package/dist/react/index.js.map +1 -0
  38. package/dist/react/purchase.d.ts +40 -0
  39. package/dist/react/purchase.d.ts.map +1 -0
  40. package/dist/react/purchase.js +81 -0
  41. package/dist/react/purchase.js.map +1 -0
  42. package/dist/react/wizard.d.ts +85 -0
  43. package/dist/react/wizard.d.ts.map +1 -0
  44. package/dist/react/wizard.js +138 -0
  45. package/dist/react/wizard.js.map +1 -0
  46. package/dist/save-file.d.ts +28 -0
  47. package/dist/save-file.d.ts.map +1 -0
  48. package/dist/save-file.js +121 -0
  49. package/dist/save-file.js.map +1 -0
  50. package/package.json +83 -0
@@ -0,0 +1,4 @@
1
+ export { DEFAULT_LEAVE_MESSAGE, useUnsavedChanges, useFocusOnChange, useWizardSteps, useSavedFlash, SaveStatus, type UnsavedChanges, type WizardSteps, type SaveStatusProps, } from './wizard.js';
2
+ export { useReportPurchase, type BuyState, type BuyNote, type DownloadOutcome, type ReportPurchaseOptions, type ReportPurchase, } from './purchase.js';
3
+ export { useEvidenceLocker, usePhoneUpload, type EvidenceLockerOptions, type EvidenceLocker, type PhoneUploadItem, type PhoneUpload, } from './evidence.js';
4
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,qBAAqB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EACrG,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,GAC5D,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,iBAAiB,EACjB,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,KAAK,cAAc,GACnG,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,iBAAiB,EAAE,cAAc,EACjC,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,GACxF,MAAM,eAAe,CAAA"}
@@ -0,0 +1,6 @@
1
+ // @unisim/assess-kit/react — hooks and components for the Assess apps
2
+ // (React 18 or 19). The framework-agnostic half is '@unisim/assess-kit'.
3
+ export { DEFAULT_LEAVE_MESSAGE, useUnsavedChanges, useFocusOnChange, useWizardSteps, useSavedFlash, SaveStatus, } from './wizard.js';
4
+ export { useReportPurchase, } from './purchase.js';
5
+ export { useEvidenceLocker, usePhoneUpload, } from './evidence.js';
6
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,yEAAyE;AAEzE,OAAO,EACL,qBAAqB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,GAEtG,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,iBAAiB,GAElB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,iBAAiB,EAAE,cAAc,GAElC,MAAM,eAAe,CAAA"}
@@ -0,0 +1,40 @@
1
+ import type { PurchaseStart, ReportOffer } from '../export-gate.js';
2
+ export type BuyState = 'idle' | 'starting' | 'waiting' | 'checking';
3
+ /**
4
+ * The line under the Buy block: `error` — the purchase couldn't be started;
5
+ * `not_paid` — Download again was still refused (the payment hasn't landed);
6
+ * `check_failed` — Download again couldn't ask the server.
7
+ */
8
+ export type BuyNote = 'error' | 'not_paid' | 'check_failed' | null;
9
+ /** What the app's gated download came to. */
10
+ export type DownloadOutcome = 'ok' | 'blocked' | 'error';
11
+ export interface ReportPurchaseOptions {
12
+ /** The refusal's offer; Buy shows only when it says canBuy (or a purchase is under way). */
13
+ offer: ReportOffer | null | undefined;
14
+ /** False hides Buy outright: the native app, or an export that can't be bought. */
15
+ enabled?: boolean;
16
+ /** Calls startReportPurchase with the SAME product, org and ref the export used. */
17
+ start: () => Promise<PurchaseStart>;
18
+ /** Re-runs the gated download, keeping the panel up. Throwing counts as 'error'. */
19
+ downloadAgain: () => Promise<DownloadOutcome>;
20
+ /** Opens the payment page. Default: a new tab. */
21
+ openPayment?: (url: string) => void;
22
+ }
23
+ export interface ReportPurchase {
24
+ buy: BuyState;
25
+ note: BuyNote;
26
+ /** The payment link, once opened — offer it again in case a popup blocker stopped the tab. */
27
+ paymentUrl: string | null;
28
+ /** The server said the buyer isn't signed in: show the sign-in prompt instead. */
29
+ needsSignIn: boolean;
30
+ /** The server said buying isn't available: Buy is gone for this panel. */
31
+ unavailable: boolean;
32
+ /** Whether to render the Buy block at all. */
33
+ showBuy: boolean;
34
+ /** Buy is waiting on payment (show "Finish paying… Download again"). */
35
+ awaitingPayment: boolean;
36
+ startBuy: () => Promise<void>;
37
+ downloadAgain: () => Promise<void>;
38
+ }
39
+ export declare function useReportPurchase({ offer, enabled, start, downloadAgain: rerun, openPayment }: ReportPurchaseOptions): ReportPurchase;
40
+ //# sourceMappingURL=purchase.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"purchase.d.ts","sourceRoot":"","sources":["../../src/react/purchase.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEnE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;AACnE;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,IAAI,CAAA;AAClE,6CAA6C;AAC7C,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAA;AAExD,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAA;IACrC,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,oFAAoF;IACpF,KAAK,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAA;IACnC,oFAAoF;IACpF,aAAa,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAA;IAC7C,kDAAkD;IAClD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,QAAQ,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;IACb,8FAA8F;IAC9F,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,kFAAkF;IAClF,WAAW,EAAE,OAAO,CAAA;IACpB,0EAA0E;IAC1E,WAAW,EAAE,OAAO,CAAA;IACpB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAA;IAChB,wEAAwE;IACxE,eAAe,EAAE,OAAO,CAAA;IACxB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAED,wBAAgB,iBAAiB,CAAC,EAAE,KAAK,EAAE,OAAc,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,qBAAqB,GAAG,cAAc,CA6C5I"}
@@ -0,0 +1,81 @@
1
+ // purchase.ts — the "Buy this report" state machine on an export-blocked
2
+ // panel (universal-platform 0218). Risk, Fire, COSHH and Cyber Assess each
3
+ // wrote it out by hand; the panels look different, the steps are the same:
4
+ //
5
+ // idle ──Buy──▶ starting ──link──▶ waiting ⇄ checking (Download again)
6
+ // │ already paid ─▶ checking
7
+ // └ refused: not_signed_in → needsSignIn
8
+ // not_available → unavailable (Buy disappears)
9
+ // failed → note 'error', back to idle
10
+ //
11
+ // The payment page opens in a NEW tab so the assessment stays open; "Download
12
+ // again" re-runs the app's gated download, which the server issues once
13
+ // Stripe's webhook has marked the report paid.
14
+ //
15
+ // ⚠️ Pass `enabled: false` inside the native app (App Store 3.1.1 / Play
16
+ // payments policy) — the hook then never offers Buy.
17
+ import { useCallback, useState } from 'react';
18
+ export function useReportPurchase({ offer, enabled = true, start, downloadAgain: rerun, openPayment }) {
19
+ const [buy, setBuy] = useState('idle');
20
+ const [note, setNote] = useState(null);
21
+ const [paymentUrl, setPaymentUrl] = useState(null);
22
+ const [needsSignIn, setNeedsSignIn] = useState(false);
23
+ const [unavailable, setUnavailable] = useState(false);
24
+ const downloadAgain = useCallback(async () => {
25
+ setBuy('checking');
26
+ setNote(null);
27
+ let outcome;
28
+ try {
29
+ outcome = await rerun();
30
+ }
31
+ catch {
32
+ outcome = 'error';
33
+ }
34
+ setBuy('waiting');
35
+ if (outcome === 'blocked')
36
+ setNote('not_paid');
37
+ else if (outcome === 'error')
38
+ setNote('check_failed');
39
+ }, [rerun]);
40
+ const startBuy = useCallback(async () => {
41
+ setBuy('starting');
42
+ setNote(null);
43
+ let res;
44
+ try {
45
+ res = await start();
46
+ }
47
+ catch {
48
+ res = { kind: 'failed' };
49
+ }
50
+ if (res.kind === 'already_paid') {
51
+ await downloadAgain();
52
+ return;
53
+ }
54
+ if (res.kind === 'pay') {
55
+ // A new tab, so the assessment stays open here.
56
+ if (openPayment)
57
+ openPayment(res.paymentUrl);
58
+ else
59
+ window.open(res.paymentUrl, '_blank', 'noopener');
60
+ setPaymentUrl(res.paymentUrl);
61
+ setBuy('waiting');
62
+ return;
63
+ }
64
+ setBuy('idle');
65
+ if (res.kind === 'refused' && res.error === 'not_signed_in')
66
+ setNeedsSignIn(true);
67
+ else if (res.kind === 'refused' && res.error === 'not_available')
68
+ setUnavailable(true);
69
+ else
70
+ setNote('error');
71
+ }, [start, downloadAgain, openPayment]);
72
+ // Once a purchase is under way the block stays, even if a retry's refusal
73
+ // no longer offers it.
74
+ const showBuy = enabled && !unavailable && !needsSignIn && (buy !== 'idle' || offer?.canBuy === true);
75
+ return {
76
+ buy, note, paymentUrl, needsSignIn, unavailable, showBuy,
77
+ awaitingPayment: buy === 'waiting' || buy === 'checking',
78
+ startBuy, downloadAgain,
79
+ };
80
+ }
81
+ //# sourceMappingURL=purchase.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"purchase.js","sourceRoot":"","sources":["../../src/react/purchase.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,85 @@
1
+ import { type CSSProperties, type RefObject } from 'react';
2
+ export declare const DEFAULT_LEAVE_MESSAGE = "You have unsaved changes. Leave without saving them?";
3
+ export interface UnsavedChanges<T> {
4
+ /** The value differs from what was last loaded or saved. */
5
+ dirty: boolean;
6
+ /** Record `value` as saved (call it when you load, and after each save). */
7
+ markSaved: (value: T) => void;
8
+ /** True when it is fine to leave: nothing unsaved, or the user said so. */
9
+ confirmLeave: (message?: string) => boolean;
10
+ }
11
+ /**
12
+ * Tracks unsaved changes to `value` (compared as JSON) and, while there are
13
+ * some, asks the browser to warn before the tab is closed or reloaded. In-app
14
+ * navigation is the app's: gate it with `confirmLeave()`.
15
+ *
16
+ * const guard = useUnsavedChanges(draft)
17
+ * const seed = (d) => { setDraft(d); guard.markSaved(d) }
18
+ * …after a save: guard.markSaved(draft)
19
+ * <button onClick={() => guard.confirmLeave() && navigate('/dashboard')}>
20
+ *
21
+ * Nothing is dirty until the first markSaved(), so a wizard still loading its
22
+ * row never warns.
23
+ */
24
+ export declare function useUnsavedChanges<T>(value: T | null | undefined, { message, serialize }?: {
25
+ message?: string;
26
+ serialize?: (v: T) => string;
27
+ }): UnsavedChanges<T>;
28
+ /**
29
+ * Moves focus to the returned element whenever `key` changes (not on the
30
+ * first render), without scrolling — so keyboard and screen-reader users land
31
+ * on the new content instead of on <body> when the button they pressed went
32
+ * away with the old one. Give the element tabIndex={-1} and a label.
33
+ *
34
+ * `onlyIfLost`: leave focus alone unless it was lost (on <body>) — for screens
35
+ * whose Back / Next buttons persist. `scroll`: also scroll it into view
36
+ * (smoothly, unless the user prefers reduced motion).
37
+ */
38
+ export declare function useFocusOnChange<E extends HTMLElement = HTMLDivElement>(key: unknown, { onlyIfLost, scroll, enabled }?: {
39
+ onlyIfLost?: boolean;
40
+ scroll?: boolean;
41
+ enabled?: boolean;
42
+ }): RefObject<E>;
43
+ export interface WizardSteps<E extends HTMLElement> {
44
+ step: number;
45
+ /** Go to step `n` (clamped) and move focus to it. */
46
+ goStep: (n: number) => void;
47
+ next: () => void;
48
+ back: () => void;
49
+ /** Set the step WITHOUT moving focus (e.g. restoring a draft's position). */
50
+ setStep: (n: number) => void;
51
+ isFirst: boolean;
52
+ isLast: boolean;
53
+ /** Put on the step's container, with tabIndex={-1} and role/aria-label. */
54
+ stepRef: RefObject<E>;
55
+ }
56
+ /**
57
+ * Step state for a wizard of `count` steps. A move made through goStep /
58
+ * next / back focuses the new step and scrolls it into view; the first render
59
+ * and setStep() do not.
60
+ */
61
+ export declare function useWizardSteps<E extends HTMLElement = HTMLDivElement>(count: number, { initial, scroll }?: {
62
+ initial?: number;
63
+ scroll?: boolean;
64
+ }): WizardSteps<E>;
65
+ /** A flag that turns itself off after `ms` — for a "Saved." confirmation. */
66
+ export declare function useSavedFlash(ms?: number): [shown: boolean, flash: () => void, clear: () => void];
67
+ export interface SaveStatusProps {
68
+ /** Just saved — shows `savedLabel`. */
69
+ saved: boolean;
70
+ /** Unsaved changes — shows `unsavedLabel` (when `canSave`). */
71
+ dirty: boolean;
72
+ /** False when saving isn't possible, so "Unsaved changes" would only nag. */
73
+ canSave?: boolean;
74
+ savedLabel?: string;
75
+ unsavedLabel?: string;
76
+ className?: string;
77
+ style?: CSSProperties;
78
+ }
79
+ /**
80
+ * The wizard's save status, in a polite live region so a screen reader hears
81
+ * "Saved." without moving focus. Always rendered (with a min-height), so the
82
+ * layout doesn't jump when it fills in.
83
+ */
84
+ export declare function SaveStatus({ saved, dirty, canSave, savedLabel, unsavedLabel, className, style, }: SaveStatusProps): import("react").JSX.Element;
85
+ //# sourceMappingURL=wizard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wizard.d.ts","sourceRoot":"","sources":["../../src/react/wizard.tsx"],"names":[],"mappings":"AAQA,OAAO,EAAqD,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAG7G,eAAO,MAAM,qBAAqB,yDAAyD,CAAA;AAE3F,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,4DAA4D;IAC5D,KAAK,EAAE,OAAO,CAAA;IACd,4EAA4E;IAC5E,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IAC7B,2EAA2E;IAC3E,YAAY,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3B,EAAE,OAA+B,EAAE,SAA8C,EAAE,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;CAAO,GAC3I,cAAc,CAAC,CAAC,CAAC,CAkBnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,GAAG,cAAc,EACrE,GAAG,EAAE,OAAO,EACZ,EAAE,UAAkB,EAAE,MAAc,EAAE,OAAc,EAAE,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACzH,SAAS,CAAC,CAAC,CAAC,CAed;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,WAAW;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,6EAA6E;IAC7E,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,2EAA2E;IAC3E,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CACtB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,cAAc,EACnE,KAAK,EAAE,MAAM,EACb,EAAE,OAAW,EAAE,MAAa,EAAE,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1E,WAAW,CAAC,CAAC,CAAC,CAoChB;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,EAAE,SAAO,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,CAW/F;AAED,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAA;IACd,+DAA+D;IAC/D,KAAK,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EAAE,KAAK,EAAE,OAAc,EAC5B,UAAqB,EAAE,YAAgC,EACvD,SAAS,EAAE,KAAK,GACjB,EAAE,eAAe,+BAMjB"}
@@ -0,0 +1,138 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ // wizard.tsx — the shell around an Assess wizard: unsaved-changes guard,
3
+ // "Saved." / "Unsaved changes" status, and moving focus to the new step.
4
+ //
5
+ // Fire and COSHH Assess grew these by hand on 2026-10-04 (identically);
6
+ // Workplace's StepShell and Cyber's QuestionFlow each had their own version of
7
+ // the focus half. The step components, labels and buttons stay in the app —
8
+ // this only carries the behaviour that kept being re-invented.
9
+ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
10
+ import { prefersReducedMotion } from '../platform.js';
11
+ export const DEFAULT_LEAVE_MESSAGE = 'You have unsaved changes. Leave without saving them?';
12
+ /**
13
+ * Tracks unsaved changes to `value` (compared as JSON) and, while there are
14
+ * some, asks the browser to warn before the tab is closed or reloaded. In-app
15
+ * navigation is the app's: gate it with `confirmLeave()`.
16
+ *
17
+ * const guard = useUnsavedChanges(draft)
18
+ * const seed = (d) => { setDraft(d); guard.markSaved(d) }
19
+ * …after a save: guard.markSaved(draft)
20
+ * <button onClick={() => guard.confirmLeave() && navigate('/dashboard')}>
21
+ *
22
+ * Nothing is dirty until the first markSaved(), so a wizard still loading its
23
+ * row never warns.
24
+ */
25
+ export function useUnsavedChanges(value, { message = DEFAULT_LEAVE_MESSAGE, serialize = JSON.stringify } = {}) {
26
+ const [saved, setSaved] = useState(null);
27
+ const current = useMemo(() => (value == null ? null : serialize(value)), [value, serialize]);
28
+ const dirty = current !== null && saved !== null && current !== saved;
29
+ useEffect(() => {
30
+ if (!dirty)
31
+ return;
32
+ const warn = (e) => { e.preventDefault(); e.returnValue = ''; };
33
+ window.addEventListener('beforeunload', warn);
34
+ return () => window.removeEventListener('beforeunload', warn);
35
+ }, [dirty]);
36
+ const markSaved = useCallback((v) => setSaved(serialize(v)), [serialize]);
37
+ const confirmLeave = useCallback((msg) => !dirty || window.confirm(msg ?? message), [dirty, message]);
38
+ return { dirty, markSaved, confirmLeave };
39
+ }
40
+ /**
41
+ * Moves focus to the returned element whenever `key` changes (not on the
42
+ * first render), without scrolling — so keyboard and screen-reader users land
43
+ * on the new content instead of on <body> when the button they pressed went
44
+ * away with the old one. Give the element tabIndex={-1} and a label.
45
+ *
46
+ * `onlyIfLost`: leave focus alone unless it was lost (on <body>) — for screens
47
+ * whose Back / Next buttons persist. `scroll`: also scroll it into view
48
+ * (smoothly, unless the user prefers reduced motion).
49
+ */
50
+ export function useFocusOnChange(key, { onlyIfLost = false, scroll = false, enabled = true } = {}) {
51
+ const ref = useRef(null);
52
+ const first = useRef(true);
53
+ useEffect(() => {
54
+ if (first.current) {
55
+ first.current = false;
56
+ return;
57
+ }
58
+ const el = ref.current;
59
+ if (!enabled || !el)
60
+ return;
61
+ const active = document.activeElement;
62
+ if (onlyIfLost && active && active !== document.body)
63
+ return;
64
+ el.focus({ preventScroll: true });
65
+ if (scroll)
66
+ el.scrollIntoView?.({ block: 'start', behavior: prefersReducedMotion() ? 'auto' : 'smooth' });
67
+ // Only a change of key moves focus — not a change of options.
68
+ // eslint-disable-next-line react-hooks/exhaustive-deps
69
+ }, [key]);
70
+ return ref;
71
+ }
72
+ /**
73
+ * Step state for a wizard of `count` steps. A move made through goStep /
74
+ * next / back focuses the new step and scrolls it into view; the first render
75
+ * and setStep() do not.
76
+ */
77
+ export function useWizardSteps(count, { initial = 0, scroll = true } = {}) {
78
+ const last = Math.max(0, count - 1);
79
+ const clamp = useCallback((n) => Math.min(last, Math.max(0, n)), [last]);
80
+ const [step, setRaw] = useState(() => Math.min(last, Math.max(0, initial)));
81
+ const moved = useRef(false);
82
+ const stepRef = useRef(null);
83
+ useEffect(() => {
84
+ if (!moved.current)
85
+ return;
86
+ moved.current = false;
87
+ const el = stepRef.current;
88
+ if (!el)
89
+ return;
90
+ el.focus({ preventScroll: true });
91
+ if (scroll)
92
+ el.scrollIntoView?.({ block: 'start', behavior: prefersReducedMotion() ? 'auto' : 'smooth' });
93
+ }, [step, scroll]);
94
+ const goStep = useCallback((n) => {
95
+ const to = clamp(n);
96
+ moved.current = true;
97
+ setRaw((cur) => {
98
+ if (cur === to)
99
+ moved.current = false;
100
+ return to;
101
+ });
102
+ }, [clamp]);
103
+ const setStep = useCallback((n) => setRaw(clamp(n)), [clamp]);
104
+ const shown = clamp(step);
105
+ return {
106
+ step: shown,
107
+ goStep,
108
+ next: useCallback(() => goStep(shown + 1), [goStep, shown]),
109
+ back: useCallback(() => goStep(shown - 1), [goStep, shown]),
110
+ setStep,
111
+ isFirst: shown === 0,
112
+ isLast: shown === last,
113
+ stepRef,
114
+ };
115
+ }
116
+ /** A flag that turns itself off after `ms` — for a "Saved." confirmation. */
117
+ export function useSavedFlash(ms = 3000) {
118
+ const [shown, setShown] = useState(false);
119
+ const [nonce, setNonce] = useState(0);
120
+ useEffect(() => {
121
+ if (!shown)
122
+ return;
123
+ const t = setTimeout(() => setShown(false), ms);
124
+ return () => clearTimeout(t);
125
+ }, [shown, nonce, ms]);
126
+ const flash = useCallback(() => { setShown(true); setNonce((n) => n + 1); }, []);
127
+ const clear = useCallback(() => setShown(false), []);
128
+ return [shown, flash, clear];
129
+ }
130
+ /**
131
+ * The wizard's save status, in a polite live region so a screen reader hears
132
+ * "Saved." without moving focus. Always rendered (with a min-height), so the
133
+ * layout doesn't jump when it fills in.
134
+ */
135
+ export function SaveStatus({ saved, dirty, canSave = true, savedLabel = 'Saved.', unsavedLabel = 'Unsaved changes', className, style, }) {
136
+ return (_jsx("div", { role: "status", "aria-live": "polite", className: className, style: { minHeight: '1.2em', ...style }, children: saved ? savedLabel : dirty && canSave ? unsavedLabel : '' }));
137
+ }
138
+ //# sourceMappingURL=wizard.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wizard.js","sourceRoot":"","sources":["../../src/react/wizard.tsx"],"names":[],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ export interface SaveFileOptions {
2
+ /** The file's contents. Pass either `blob` or `data`. */
3
+ blob?: Blob;
4
+ /** Raw contents: a string (saved as text) or bytes. Ignored when `blob` is set. */
5
+ data?: string | ArrayBuffer | Uint8Array;
6
+ /** Suggested file name, including the extension, e.g. `report.pdf`. */
7
+ filename: string;
8
+ /** MIME type, e.g. `application/pdf`. Defaults to the blob's own type. */
9
+ mimeType?: string;
10
+ /** Optional title for the share sheet (Android shows it; iOS mostly ignores it). */
11
+ title?: string;
12
+ }
13
+ /**
14
+ * What happened:
15
+ * - `shared` — a share sheet opened and the user picked a destination
16
+ * - `downloaded` — the browser download was triggered
17
+ * - `cancelled` — the user dismissed the share sheet
18
+ */
19
+ export type SaveFileResult = 'shared' | 'downloaded' | 'cancelled';
20
+ /** Strips characters that file systems or share targets choke on. */
21
+ export declare function safeFileName(name: string): string;
22
+ /** The options' contents as one Blob of the right type. */
23
+ export declare function toBlob(opts: Pick<SaveFileOptions, 'blob' | 'data' | 'mimeType'>): Blob;
24
+ /** A Blob as plain base64 (no `data:` prefix) — what Filesystem.writeFile takes. */
25
+ export declare function blobToBase64(blob: Blob): Promise<string>;
26
+ /** Saves / shares a file in whatever way the current platform supports. */
27
+ export declare function saveFile(opts: SaveFileOptions): Promise<SaveFileResult>;
28
+ //# sourceMappingURL=save-file.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"save-file.d.ts","sourceRoot":"","sources":["../src/save-file.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAA;IACxC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,YAAY,GAAG,WAAW,CAAA;AAElE,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,2DAA2D;AAC3D,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC,GAAG,IAAI,CAUtF;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAUxD;AA2CD,2EAA2E;AAC3E,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAqB7E"}
@@ -0,0 +1,121 @@
1
+ // save-file.ts — hand a generated file (PDF, CSV, JSON…) to the user, on every
2
+ // platform an Assess app runs on.
3
+ //
4
+ // Why this exists: the usual web trick — `URL.createObjectURL(blob)` plus a
5
+ // synthetic `<a download>` click (which is also all jsPDF's `doc.save()` does)
6
+ // silently does NOTHING inside a Capacitor WKWebView (iOS) or Android WebView,
7
+ // and neither does window.print(). There is no download manager or print
8
+ // dialog behind the web view, so every export button in the phone apps was
9
+ // dead until each app grew its own copy of this file (Cyber 2026-09-28, then
10
+ // Workplace, then Fire / COSHH / Risk on 2026-10-04). This is that file, once.
11
+ //
12
+ // · Native (Capacitor iOS / Android): write the file into the app's cache
13
+ // directory with @capacitor/filesystem, then open the system share sheet on
14
+ // it with @capacitor/share — Save to Files, Mail, AirDrop, Drive, Print…
15
+ // (Android: the share goes through Capacitor's FileProvider, whose
16
+ // res/xml/file_paths.xml needs a <cache-path path=".">.)
17
+ // · Web on a touch device that can share files (iOS Safari, Android Chrome,
18
+ // an installed PWA): navigator.share({ files }) — the same sheet.
19
+ // · Everywhere else (desktop browsers): the ordinary <a download>.
20
+ //
21
+ // The Capacitor plugins are optional peer dependencies, imported dynamically
22
+ // and only inside the native shell, so a web bundle never loads them.
23
+ import { isNativeApp, isTouchDevice } from './platform.js';
24
+ /** Strips characters that file systems or share targets choke on. */
25
+ export function safeFileName(name) {
26
+ const cleaned = Array.from(String(name ?? ''), (ch) => (ch.charCodeAt(0) < 32 ? '-' : ch))
27
+ .join('')
28
+ .replace(/[\\/:*?"<>|]+/g, '-')
29
+ .replace(/\s+/g, ' ')
30
+ .trim();
31
+ return cleaned || 'download';
32
+ }
33
+ /** The options' contents as one Blob of the right type. */
34
+ export function toBlob(opts) {
35
+ if (opts.blob) {
36
+ return opts.mimeType && opts.blob.type !== opts.mimeType
37
+ ? new Blob([opts.blob], { type: opts.mimeType })
38
+ : opts.blob;
39
+ }
40
+ const type = opts.mimeType ?? (typeof opts.data === 'string' ? 'text/plain' : 'application/octet-stream');
41
+ const data = opts.data ?? '';
42
+ const part = data instanceof Uint8Array ? new Uint8Array(data) : data;
43
+ return new Blob([part], { type });
44
+ }
45
+ /** A Blob as plain base64 (no `data:` prefix) — what Filesystem.writeFile takes. */
46
+ export function blobToBase64(blob) {
47
+ return new Promise((resolve, reject) => {
48
+ const reader = new FileReader();
49
+ reader.onerror = () => reject(reader.error ?? new Error('Could not read the file'));
50
+ reader.onload = () => {
51
+ const url = String(reader.result ?? '');
52
+ resolve(url.slice(url.indexOf(',') + 1));
53
+ };
54
+ reader.readAsDataURL(blob);
55
+ });
56
+ }
57
+ function isCancel(err) {
58
+ if (err instanceof DOMException && err.name === 'AbortError')
59
+ return true;
60
+ const msg = err instanceof Error ? err.message : String(err ?? '');
61
+ return /cancel|abort|dismiss/i.test(msg);
62
+ }
63
+ async function saveNative(blob, filename, title) {
64
+ const [{ Filesystem, Directory }, { Share }] = await Promise.all([
65
+ import('@capacitor/filesystem'),
66
+ import('@capacitor/share'),
67
+ ]);
68
+ const written = await Filesystem.writeFile({
69
+ path: filename,
70
+ data: await blobToBase64(blob),
71
+ directory: Directory.Cache,
72
+ recursive: true,
73
+ });
74
+ try {
75
+ await Share.share({ title: title ?? filename, files: [written.uri], dialogTitle: title ?? filename });
76
+ return 'shared';
77
+ }
78
+ catch (err) {
79
+ if (isCancel(err))
80
+ return 'cancelled';
81
+ throw err;
82
+ }
83
+ }
84
+ function download(blob, filename) {
85
+ const url = URL.createObjectURL(blob);
86
+ const a = document.createElement('a');
87
+ a.href = url;
88
+ a.download = filename;
89
+ a.rel = 'noopener';
90
+ a.style.display = 'none';
91
+ document.body.appendChild(a);
92
+ a.click();
93
+ a.remove();
94
+ // Revoking synchronously can cancel the download in some browsers.
95
+ setTimeout(() => URL.revokeObjectURL(url), 60_000);
96
+ return 'downloaded';
97
+ }
98
+ /** Saves / shares a file in whatever way the current platform supports. */
99
+ export async function saveFile(opts) {
100
+ const filename = safeFileName(opts.filename);
101
+ const blob = toBlob(opts);
102
+ if (isNativeApp())
103
+ return saveNative(blob, filename, opts.title);
104
+ if (isTouchDevice() && typeof navigator.share === 'function' && typeof navigator.canShare === 'function') {
105
+ const file = new File([blob], filename, { type: blob.type });
106
+ if (navigator.canShare({ files: [file] })) {
107
+ try {
108
+ await navigator.share({ files: [file], title: opts.title ?? filename });
109
+ return 'shared';
110
+ }
111
+ catch (err) {
112
+ if (err instanceof DOMException && err.name === 'AbortError')
113
+ return 'cancelled';
114
+ // NotAllowedError: the tap's user activation expired while the file
115
+ // was being generated. Fall through to a normal download.
116
+ }
117
+ }
118
+ }
119
+ return download(blob, filename);
120
+ }
121
+ //# sourceMappingURL=save-file.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"save-file.js","sourceRoot":"","sources":["../src/save-file.ts"],"names":[],"mappings":"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"}
package/package.json ADDED
@@ -0,0 +1,83 @@
1
+ {
2
+ "name": "@unisim/assess-kit",
3
+ "version": "0.1.0",
4
+ "description": "What every Assess app shares: saving a file on web and phone, PDF fonts, the server export gate, the evidence locker and the wizard shell — one copy instead of five drifting ones.",
5
+ "license": "MIT",
6
+ "author": "Universal Simulation Ltd",
7
+ "keywords": [
8
+ "assess",
9
+ "supabase",
10
+ "capacitor",
11
+ "jspdf",
12
+ "pdf-lib",
13
+ "react",
14
+ "universal-simulation"
15
+ ],
16
+ "homepage": "https://github.com/universal-simulation-ltd/universal-platform/tree/main/packages/assess-kit#readme",
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/universal-simulation-ltd/universal-platform.git",
20
+ "directory": "packages/assess-kit"
21
+ },
22
+ "bugs": {
23
+ "url": "https://github.com/universal-simulation-ltd/universal-platform/issues"
24
+ },
25
+ "type": "module",
26
+ "main": "./dist/index.js",
27
+ "module": "./dist/index.js",
28
+ "types": "./dist/index.d.ts",
29
+ "sideEffects": false,
30
+ "exports": {
31
+ ".": {
32
+ "types": "./dist/index.d.ts",
33
+ "import": "./dist/index.js"
34
+ },
35
+ "./react": {
36
+ "types": "./dist/react/index.d.ts",
37
+ "import": "./dist/react/index.js"
38
+ }
39
+ },
40
+ "files": [
41
+ "dist",
42
+ "README.md"
43
+ ],
44
+ "scripts": {
45
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
46
+ "dev": "tsc -p tsconfig.build.json --watch",
47
+ "typecheck": "tsc --noEmit",
48
+ "test": "vitest run",
49
+ "prepublishOnly": "npm run typecheck && npm test && npm run build"
50
+ },
51
+ "peerDependencies": {
52
+ "@capacitor/filesystem": ">=6",
53
+ "@capacitor/share": ">=6",
54
+ "react": "^18.0.0 || ^19.0.0"
55
+ },
56
+ "peerDependenciesMeta": {
57
+ "@capacitor/filesystem": {
58
+ "optional": true
59
+ },
60
+ "@capacitor/share": {
61
+ "optional": true
62
+ },
63
+ "react": {
64
+ "optional": true
65
+ }
66
+ },
67
+ "devDependencies": {
68
+ "@capacitor/core": "^8.5.2",
69
+ "@capacitor/filesystem": "^8.1.4",
70
+ "@capacitor/share": "^8.0.3",
71
+ "@types/react": "^18.3.0",
72
+ "@types/react-dom": "^18.3.7",
73
+ "happy-dom": "^20.0.0",
74
+ "pdf-lib": "^1.17.1",
75
+ "react": "^18.3.0",
76
+ "react-dom": "^18.3.1",
77
+ "typescript": "^5.7.2",
78
+ "vitest": "^3.2.4"
79
+ },
80
+ "publishConfig": {
81
+ "access": "public"
82
+ }
83
+ }