@tantainnovative/ndpr-toolkit 3.10.6 → 3.12.0

package/dist/hooks.d.ts

@@ -1400,6 +1400,28 @@ declare interface TransferValidationResult {
     warnings: string[];
 }
 
+/**
+ * Multi-step privacy-policy authoring hook that adapts the generated draft
+ * to the supplied template context (industry, processing purposes, data
+ * categories, processors). Auto-persists a draft via the supplied adapter
+ * and surfaces a live compliance score against the configured rule set.
+ *
+ * @example
+ * ```tsx
+ * import { useAdaptivePolicyWizard } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function PolicyWizard() {
+ *   const { currentStep, nextStep, policy, complianceScore } = useAdaptivePolicyWizard();
+ *   return (
+ *     <div>
+ *       <p>Step {currentStep} — compliance: {complianceScore}%</p>
+ *       <button onClick={nextStep}>Next</button>
+ *       {policy && <pre>{policy.title}</pre>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function useAdaptivePolicyWizard(options?: UseAdaptivePolicyWizardOptions): UseAdaptivePolicyWizardReturn;
 
 export declare interface UseAdaptivePolicyWizardOptions {
@@ -1460,11 +1482,23 @@ export declare interface UseAdaptivePolicyWizardReturn {
 }
 
 /**
- * Hook for managing data breach notifications in compliance with the NDPA (Section 40)
+ * Hook for managing data breach notifications in compliance with the NDPA (Section 40).
+ *
+ * @example
+ * ```tsx
+ * import { useBreach } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function BreachConsole() {
+ *   const { reports, reportBreach } = useBreach({
+ *     categories: [{ id: 'unauthorized-access', name: 'Unauthorised access', description: '' }],
+ *   });
+ *   return <p>{reports.length} breach report(s) on record.</p>;
+ * }
+ * ```
  */
 export declare function useBreach({ categories, initialReports, adapter, storageKey, useLocalStorage, onReport, onAssessment, onNotification, }: UseBreachOptions): UseBreachReturn;
 
-declare interface UseBreachOptions {
+export declare interface UseBreachOptions {
     /**
      * Available breach categories
      */
@@ -1503,7 +1537,7 @@ declare interface UseBreachOptions {
     onNotification?: (notification: RegulatoryNotification) => void;
 }
 
-declare interface UseBreachReturn {
+export declare interface UseBreachReturn {
     /**
      * All breach reports
      */
@@ -1567,18 +1601,69 @@ declare interface UseBreachReturn {
     isLoading: boolean;
 }
 
+/**
+ * Computes an NDPA compliance score and returns a structured report
+ * (score, rating, per-module breakdown, recommendations).
+ *
+ * The computation is memoised by the structural identity of `input` — passing
+ * a fresh-but-equal object on every render is safe and does not force a recompute.
+ *
+ * @param options - The compliance score options.
+ * @param options.input - A {@link ComplianceInput} snapshot summarising the
+ *   organisation's current compliance posture.
+ * @returns A memoised {@link ComplianceReport} with overall score, rating,
+ *   module-level breakdowns, and prioritised recommendations.
+ *
+ * @example
+ * ```tsx
+ * import { useComplianceScore } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function ComplianceBadge({ input }) {
+ *   const report = useComplianceScore({ input });
+ *   return <span>{report.overallScore}/100 — {report.rating}</span>;
+ * }
+ * ```
+ */
 export declare function useComplianceScore({ input }: UseComplianceScoreOptions): ComplianceReport;
 
-declare interface UseComplianceScoreOptions {
+export declare interface UseComplianceScoreOptions {
+    /**
+     * Snapshot of the organisation's compliance signals — consent settings,
+     * DSR queue, breach log, lawful-basis register, transfers, ROPA, etc.
+     * The hook recomputes the report whenever this input changes by value
+     * (compared via a stable JSON key under the hood).
+     */
     input: ComplianceInput;
 }
 
 /**
- * Hook for managing user consent in compliance with NDPA
+ * Hook for managing user consent in compliance with the NDPA.
+ *
+ * @example
+ * ```tsx
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function App() {
+ *   const { hasConsent, acceptAll, rejectAll, shouldShowBanner } = useConsent({
+ *     options: [
+ *       { id: 'necessary', label: 'Necessary', required: true },
+ *       { id: 'analytics', label: 'Analytics' },
+ *     ],
+ *   });
+ *   if (!shouldShowBanner) return null;
+ *   return (
+ *     <div role="dialog">
+ *       <button onClick={acceptAll}>Accept all</button>
+ *       <button onClick={rejectAll}>Reject non-essential</button>
+ *       {hasConsent('analytics') && <AnalyticsScripts />}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function useConsent({ options, adapter, storageOptions, version, onChange, }: UseConsentOptions): UseConsentReturn;
 
-declare interface UseConsentOptions {
+export declare interface UseConsentOptions {
     /**
      * Consent options to present to the user
      */
@@ -1603,7 +1688,7 @@ declare interface UseConsentOptions {
     onChange?: (settings: ConsentSettings) => void;
 }
 
-declare interface UseConsentReturn {
+export declare interface UseConsentReturn {
     /**
      * Current consent settings
      */
@@ -1647,11 +1732,22 @@ declare interface UseConsentReturn {
 }
 
 /**
- * Hook for managing cross-border data transfers in compliance with NDPA Part VIII (Sections 41-43)
+ * Hook for managing cross-border data transfers in compliance with NDPA Part VIII (Sections 41-43).
+ *
+ * @example
+ * ```tsx
+ * import { useCrossBorderTransfer } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function TransferRegister() {
+ *   const { transfers, getSummary } = useCrossBorderTransfer();
+ *   const summary = getSummary();
+ *   return <p>{summary.totalActiveTransfers} active cross-border transfers.</p>;
+ * }
+ * ```
  */
 export declare function useCrossBorderTransfer({ initialTransfers, adapter, storageKey, useLocalStorage, onAdd, onUpdate, onRemove, }?: UseCrossBorderTransferOptions): UseCrossBorderTransferReturn;
 
-declare interface UseCrossBorderTransferOptions {
+export declare interface UseCrossBorderTransferOptions {
     /**
      * Initial transfers to load
      */
@@ -1686,7 +1782,7 @@ declare interface UseCrossBorderTransferOptions {
     onRemove?: (id: string) => void;
 }
 
-declare interface UseCrossBorderTransferReturn {
+export declare interface UseCrossBorderTransferReturn {
     /**
      * All cross-border transfers
      */
@@ -1793,11 +1889,26 @@ declare interface UseDefaultPrivacyPolicyOptions {
 }
 
 /**
- * Hook for conducting Data Protection Impact Assessments in compliance with the NDPA 2023
+ * Hook for conducting Data Protection Impact Assessments in compliance with the NDPA 2023.
+ *
+ * @example
+ * ```tsx
+ * import { useDPIA } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function DPIAWizard({ sections }) {
+ *   const { currentSection, progress, updateAnswer, nextSection } = useDPIA({ sections });
+ *   return (
+ *     <div>
+ *       <h2>{currentSection?.title} ({progress}%)</h2>
+ *       <button onClick={nextSection}>Next</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function useDPIA({ sections, initialAnswers, adapter, storageKey, useLocalStorage, onComplete, }: UseDPIAOptions): UseDPIAReturn;
 
-declare interface UseDPIAOptions {
+export declare interface UseDPIAOptions {
     /**
      * Sections of the DPIA questionnaire
      */
@@ -1828,7 +1939,7 @@ declare interface UseDPIAOptions {
     onComplete?: (result: DPIAResult) => void;
 }
 
-declare interface UseDPIAReturn {
+export declare interface UseDPIAReturn {
     /**
      * Current section index
      */
@@ -1896,11 +2007,31 @@ declare interface UseDPIAReturn {
 }
 
 /**
- * Hook for managing Data Subject Requests in compliance with the NDPA
+ * Hook for managing Data Subject Requests in compliance with the NDPA.
+ *
+ * @example
+ * ```tsx
+ * import { useDSR } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function DSRPanel() {
+ *   const { requests, submitRequest } = useDSR({
+ *     requestTypes: [
+ *       { id: 'access', name: 'Access', description: 'Request access', estimatedCompletionTime: 30 },
+ *     ],
+ *   });
+ *   return (
+ *     <ul>
+ *       {requests.map((r) => (
+ *         <li key={r.id}>{r.type} — {r.status}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
  */
 export declare function useDSR({ initialRequests, requestTypes, adapter, storageKey, useLocalStorage, onSubmit, onUpdate, }: UseDSROptions): UseDSRReturn;
 
-declare interface UseDSROptions {
+export declare interface UseDSROptions {
     /**
      * Initial requests to load
      */
@@ -1935,7 +2066,7 @@ declare interface UseDSROptions {
     onUpdate?: (request: DSRRequest) => void;
 }
 
-declare interface UseDSRReturn {
+export declare interface UseDSRReturn {
     /**
      * All requests
      */
@@ -2021,10 +2152,20 @@ export declare interface UseFocusTrapOptions {
 /**
  * Hook for managing lawful basis documentation for processing activities
  * in compliance with NDPA 2023 Section 25.
+ *
+ * @example
+ * ```tsx
+ * import { useLawfulBasis } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function LawfulBasisRegistry() {
+ *   const { activities, addActivity } = useLawfulBasis();
+ *   return <p>{activities.length} processing activities documented.</p>;
+ * }
+ * ```
  */
 export declare function useLawfulBasis({ initialActivities, adapter, storageKey, useLocalStorage, onAdd, onUpdate, onRemove, }?: UseLawfulBasisOptions): UseLawfulBasisReturn;
 
-declare interface UseLawfulBasisOptions {
+export declare interface UseLawfulBasisOptions {
     /**
      * Initial processing activities to load
      */
@@ -2059,7 +2200,7 @@ declare interface UseLawfulBasisOptions {
     onRemove?: (id: string) => void;
 }
 
-declare interface UseLawfulBasisReturn {
+export declare interface UseLawfulBasisReturn {
     /**
      * All processing activities
      */
@@ -2095,11 +2236,27 @@ declare interface UseLawfulBasisReturn {
 }
 
 /**
- * Hook for generating NDPA-compliant privacy policies
+ * Hook for generating NDPA-compliant privacy policies.
+ *
+ * @example
+ * ```tsx
+ * import { usePrivacyPolicy } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function PolicyBuilder({ templates }) {
+ *   const { policy, selectTemplate, generatePolicy } = usePrivacyPolicy({ templates });
+ *   return (
+ *     <div>
+ *       <button onClick={() => selectTemplate(templates[0].id)}>Select default</button>
+ *       <button onClick={generatePolicy}>Generate</button>
+ *       {policy && <pre>{policy.title}</pre>}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function usePrivacyPolicy({ templates, initialPolicy, adapter, storageKey, persist, useLocalStorage, onGenerate, }: UsePrivacyPolicyOptions): UsePrivacyPolicyReturn;
 
-declare interface UsePrivacyPolicyOptions {
+export declare interface UsePrivacyPolicyOptions {
     /**
      * Available policy templates
      */
@@ -2139,7 +2296,7 @@ declare interface UsePrivacyPolicyOptions {
     onGenerate?: (policy: PrivacyPolicy) => void;
 }
 
-declare interface UsePrivacyPolicyReturn {
+export declare interface UsePrivacyPolicyReturn {
     /**
      * Current policy data
      */
@@ -2207,6 +2364,21 @@ declare interface UsePrivacyPolicyReturn {
  *
  * Provides state management and utility functions for maintaining
  * a comprehensive register of all data processing activities.
+ *
+ * @example
+ * ```tsx
+ * import { useROPA } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function ROPARegister({ initialData }) {
+ *   const { ropa, addRecord, exportCSV } = useROPA({ initialData });
+ *   return (
+ *     <div>
+ *       <p>{ropa.records.length} processing records</p>
+ *       <button onClick={() => download(exportCSV())}>Export CSV</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function useROPA({ initialData, adapter, onRecordAdd, onRecordUpdate, onRecordArchive, }: UseROPAOptions): UseROPAReturn;
 
@@ -2257,17 +2429,38 @@ export declare interface UseROPAReturn {
      */
     getRecord: (id: string) => ProcessingRecord | undefined;
     /**
-     * Get a summary of the ROPA including statistics
+     * Get a summary of the ROPA including statistics.
+     * @deprecated Use the cached `summary` field instead — it is memoised on
+     * `ropa` so consumers don't pay the recompute cost on every call.
      */
     getSummary: () => ROPASummary;
     /**
-     * Export the ROPA as a CSV string
+     * Export the ROPA as a CSV string.
+     * @deprecated Use the cached `csv` field instead — it is memoised on
+     * `ropa` so consumers don't pay the recompute cost on every call.
      */
     exportCSV: () => string;
     /**
-     * Identify compliance gaps across all records
+     * Identify compliance gaps across all records.
+     * @deprecated Use the cached `complianceGaps` field instead — it is
+     * memoised on `ropa` so consumers don't pay the recompute cost on every call.
      */
     getComplianceGaps: () => ROPAComplianceGap[];
+    /**
+     * Memoised ROPA summary. Recomputed only when `ropa` changes.
+     * Prefer this over `getSummary()` to avoid redundant recomputation.
+     */
+    summary: ROPASummary;
+    /**
+     * Memoised CSV export string. Recomputed only when `ropa` changes.
+     * Prefer this over `exportCSV()` to avoid redundant recomputation.
+     */
+    csv: string;
+    /**
+     * Memoised compliance gap list. Recomputed only when `ropa` changes.
+     * Prefer this over `getComplianceGaps()` to avoid redundant recomputation.
+     */
+    complianceGaps: ROPAComplianceGap[];
     /**
      * Whether the adapter is still loading data (relevant for async adapters)
      */

package/dist/hooks.js

@@ -1,2 +1,2 @@
 "use client";
-'use strict';require('./chunk-OZCNFB5C.js');var chunkCNM6G5IA_js=require('./chunk-CNM6G5IA.js'),chunkVJTQXVAF_js=require('./chunk-VJTQXVAF.js'),chunkRC3XFXTJ_js=require('./chunk-RC3XFXTJ.js'),chunkQHW4UKGJ_js=require('./chunk-QHW4UKGJ.js'),chunkUTFBKL73_js=require('./chunk-UTFBKL73.js'),chunkHHK5LHEG_js=require('./chunk-HHK5LHEG.js'),chunk3JPDTXGC_js=require('./chunk-3JPDTXGC.js');require('./chunk-JS7SYL5P.js'),require('./chunk-RDALAH3Y.js'),require('./chunk-3YTAOT5O.js'),require('./chunk-D2ZKDQVL.js'),require('./chunk-6LJHLE6G.js'),require('./chunk-YFBDJ4FH.js'),require('./chunk-WZYCBW2R.js'),require('./chunk-4CVBQC66.js');var chunkH3IULCE3_js=require('./chunk-H3IULCE3.js'),chunkL2VO3MEJ_js=require('./chunk-L2VO3MEJ.js');require('./chunk-C2KEXHRX.js'),require('./chunk-B46SJB5V.js');var chunkHBLGN4SD_js=require('./chunk-HBLGN4SD.js');require('./chunk-L2BRFMVS.js');var chunkC7IDR2IV_js=require('./chunk-C7IDR2IV.js');require('./chunk-TQZWJGJ2.js'),require('./chunk-ZVOIR4QH.js'),require('./chunk-VWED6UTN.js'),require('./chunk-RFPLZDIO.js');Object.defineProperty(exports,"useComplianceScore",{enumerable:true,get:function(){return chunkCNM6G5IA_js.a}});Object.defineProperty(exports,"useBreach",{enumerable:true,get:function(){return chunkVJTQXVAF_js.a}});Object.defineProperty(exports,"useDefaultPrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.b}});Object.defineProperty(exports,"usePrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.a}});Object.defineProperty(exports,"useAdaptivePolicyWizard",{enumerable:true,get:function(){return chunkQHW4UKGJ_js.a}});Object.defineProperty(exports,"useLawfulBasis",{enumerable:true,get:function(){return chunkUTFBKL73_js.a}});Object.defineProperty(exports,"useCrossBorderTransfer",{enumerable:true,get:function(){return chunkHHK5LHEG_js.a}});Object.defineProperty(exports,"useROPA",{enumerable:true,get:function(){return chunk3JPDTXGC_js.a}});Object.defineProperty(exports,"useConsent",{enumerable:true,get:function(){return chunkH3IULCE3_js.a}});Object.defineProperty(exports,"useFocusTrap",{enumerable:true,get:function(){return chunkL2VO3MEJ_js.a}});Object.defineProperty(exports,"useDSR",{enumerable:true,get:function(){return chunkHBLGN4SD_js.a}});Object.defineProperty(exports,"useDPIA",{enumerable:true,get:function(){return chunkC7IDR2IV_js.a}});
+'use strict';require('./chunk-OZCNFB5C.js');var chunkFC3PTJFL_js=require('./chunk-FC3PTJFL.js'),chunkEHQVTFYO_js=require('./chunk-EHQVTFYO.js'),chunkRC3XFXTJ_js=require('./chunk-RC3XFXTJ.js'),chunkQHW4UKGJ_js=require('./chunk-QHW4UKGJ.js'),chunkIRRUYR6M_js=require('./chunk-IRRUYR6M.js'),chunkHHK5LHEG_js=require('./chunk-HHK5LHEG.js'),chunkO2WEABB3_js=require('./chunk-O2WEABB3.js');require('./chunk-JS7SYL5P.js'),require('./chunk-RDALAH3Y.js'),require('./chunk-3YTAOT5O.js'),require('./chunk-D2ZKDQVL.js'),require('./chunk-6LJHLE6G.js'),require('./chunk-YFBDJ4FH.js'),require('./chunk-WZYCBW2R.js'),require('./chunk-4CVBQC66.js');var chunkHOAC5VUF_js=require('./chunk-HOAC5VUF.js'),chunkL2VO3MEJ_js=require('./chunk-L2VO3MEJ.js');require('./chunk-C2KEXHRX.js'),require('./chunk-B46SJB5V.js');var chunk5AECGMEB_js=require('./chunk-5AECGMEB.js');require('./chunk-OZHUINWS.js');var chunkJLQT3W3E_js=require('./chunk-JLQT3W3E.js');require('./chunk-TQZWJGJ2.js'),require('./chunk-ZVOIR4QH.js'),require('./chunk-VWED6UTN.js'),require('./chunk-RFPLZDIO.js');Object.defineProperty(exports,"useComplianceScore",{enumerable:true,get:function(){return chunkFC3PTJFL_js.a}});Object.defineProperty(exports,"useBreach",{enumerable:true,get:function(){return chunkEHQVTFYO_js.a}});Object.defineProperty(exports,"useDefaultPrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.b}});Object.defineProperty(exports,"usePrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.a}});Object.defineProperty(exports,"useAdaptivePolicyWizard",{enumerable:true,get:function(){return chunkQHW4UKGJ_js.a}});Object.defineProperty(exports,"useLawfulBasis",{enumerable:true,get:function(){return chunkIRRUYR6M_js.a}});Object.defineProperty(exports,"useCrossBorderTransfer",{enumerable:true,get:function(){return chunkHHK5LHEG_js.a}});Object.defineProperty(exports,"useROPA",{enumerable:true,get:function(){return chunkO2WEABB3_js.a}});Object.defineProperty(exports,"useConsent",{enumerable:true,get:function(){return chunkHOAC5VUF_js.a}});Object.defineProperty(exports,"useFocusTrap",{enumerable:true,get:function(){return chunkL2VO3MEJ_js.a}});Object.defineProperty(exports,"useDSR",{enumerable:true,get:function(){return chunk5AECGMEB_js.a}});Object.defineProperty(exports,"useDPIA",{enumerable:true,get:function(){return chunkJLQT3W3E_js.a}});

package/dist/hooks.mjs

@@ -1,2 +1,2 @@
 "use client";
-import'./chunk-GQYBS3A7.mjs';export{a as useComplianceScore}from'./chunk-MOHBL6LX.mjs';export{a as useBreach}from'./chunk-3HOXQNCH.mjs';export{b as useDefaultPrivacyPolicy,a as usePrivacyPolicy}from'./chunk-UVXS7KRV.mjs';export{a as useAdaptivePolicyWizard}from'./chunk-KE2FZH2V.mjs';export{a as useLawfulBasis}from'./chunk-4G3SRVRI.mjs';export{a as useCrossBorderTransfer}from'./chunk-KDAZQO3N.mjs';export{a as useROPA}from'./chunk-RPXRPGHL.mjs';import'./chunk-IVSNHT24.mjs';import'./chunk-7RBO42IW.mjs';import'./chunk-WTGKZX7J.mjs';import'./chunk-NBQQ2GN3.mjs';import'./chunk-BIJSMSUU.mjs';import'./chunk-7BJXI2HI.mjs';import'./chunk-LWIKDDSU.mjs';import'./chunk-XP5PL6K7.mjs';export{a as useConsent}from'./chunk-TAHSSITO.mjs';export{a as useFocusTrap}from'./chunk-YTU4FNM2.mjs';import'./chunk-XC3DLYEG.mjs';import'./chunk-PJNKQPQP.mjs';export{a as useDSR}from'./chunk-MPBPAEZC.mjs';import'./chunk-RZ6GC6WN.mjs';export{a as useDPIA}from'./chunk-H3XJV2IR.mjs';import'./chunk-LRRENTT5.mjs';import'./chunk-ITCY2Z66.mjs';import'./chunk-DBZSN4WP.mjs';import'./chunk-ZJYULEER.mjs';
+import'./chunk-GQYBS3A7.mjs';export{a as useComplianceScore}from'./chunk-IQO3SIAG.mjs';export{a as useBreach}from'./chunk-RFXGD5NE.mjs';export{b as useDefaultPrivacyPolicy,a as usePrivacyPolicy}from'./chunk-UVXS7KRV.mjs';export{a as useAdaptivePolicyWizard}from'./chunk-KE2FZH2V.mjs';export{a as useLawfulBasis}from'./chunk-B6BRD5SL.mjs';export{a as useCrossBorderTransfer}from'./chunk-KDAZQO3N.mjs';export{a as useROPA}from'./chunk-WKUC65HL.mjs';import'./chunk-IVSNHT24.mjs';import'./chunk-7RBO42IW.mjs';import'./chunk-WTGKZX7J.mjs';import'./chunk-NBQQ2GN3.mjs';import'./chunk-BIJSMSUU.mjs';import'./chunk-7BJXI2HI.mjs';import'./chunk-LWIKDDSU.mjs';import'./chunk-XP5PL6K7.mjs';export{a as useConsent}from'./chunk-IHNAFXDM.mjs';export{a as useFocusTrap}from'./chunk-YTU4FNM2.mjs';import'./chunk-XC3DLYEG.mjs';import'./chunk-PJNKQPQP.mjs';export{a as useDSR}from'./chunk-IB3KSUPZ.mjs';import'./chunk-VPNK7OID.mjs';export{a as useDPIA}from'./chunk-I3V3ITN7.mjs';import'./chunk-LRRENTT5.mjs';import'./chunk-ITCY2Z66.mjs';import'./chunk-DBZSN4WP.mjs';import'./chunk-ZJYULEER.mjs';