@tantainnovative/ndpr-toolkit 3.10.6 → 3.12.0

package/dist/hooks.d.mts

@@ -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)
      */