@tantainnovative/ndpr-toolkit 3.10.6 → 3.12.0

package/CHANGELOG.md

@@ -2,6 +2,117 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [3.12.0](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.11.0...v3.12.0) (2026-05-27)
+
+Release 4 of 6 on the post-audit roadmap. Accessibility + performance + test coverage. No public API changes — everything is additive or behaviour-preserving internal work. Existing consumers see no breakage; users of assistive tech and consumers of large managers see real improvements.
+
+### Accessibility — 6 WCAG 2.2 fixes
+
+- **`BreachNotificationManager`** (`components/breach/BreachNotificationManager.tsx`) — the breach list row was a clickable `<div>` without `role`/`tabIndex`/keyboard handler. Now `role="button"`, `tabIndex={0}`, `aria-selected`, `aria-label`, and Enter/Space activation (matching the existing DSRDashboard pattern). Keyboard users can finally drill into a breach row.
+- **`dpia/StepIndicator`** — the step wedge had `onClick` without button semantics. Now conditionally adds `role="button"` / `tabIndex` / keydown when interactive (`clickable && onStepClick`); when display-only, those attributes are `undefined` so it stays a non-interactive progress marker.
+- **`CrossBorderTransferManager`** — 8 form fields had `<label>` without `htmlFor` and the matching `<input>`/`<select>` had no `id`. Screen readers announced "edit text, blank" for all 8. Added stable `cb-transfer-<field>` id pairs: `riskLevel`, `estimatedDataSubjects`, `recipientContactPhone`, `recipientContactAddress`, `frequency`, `status`, `ndpcApprovalReference`, `tiaReference`.
+- **`BreachReportForm` file upload** — `<label>` had no `htmlFor`, `<input type="file">` had no `id`. Added `htmlFor="breach-attachments"` + matching id. Decorative paperclip SVG got `aria-hidden="true" focusable="false"`.
+- **Touch targets** — `.ndpr-consent-banner__button` and `.ndpr-button` were ~33px tall (`padding: 0.5rem 1rem`). Added `min-height: 44px` to both — matches iOS HIG and WCAG 2.2 enhanced target. Existing padding is unchanged so visual layout doesn't shift.
+- **`DPIAQuestionnaire`** — section title heading now has `aria-live="polite"` so screen readers announce the new section title when the user clicks Next.
+
+### Performance — 3 hot-path improvements
+
+- **`useROPA`** (`hooks/useROPA.ts`) — derivers `getSummary` / `exportCSV` / `getComplianceGaps` previously recomputed on every call. Hook now also returns `summary` / `csv` / `complianceGaps` as `useMemo`-cached values keyed on `ropa`. The existing callable functions still work (marked `@deprecated` in JSDoc, points at the cached fields). Pure additive — no break.
+- **`CrossBorderTransferManager`** — `summaryData` collapsed from 4× `transfers.filter(...)` calls (O(4n)) to a single `for` loop (O(n)) that accumulates `totalActiveTransfers`, `pendingApproval`, `highRiskTransfers`, `missingTIA` in one pass. Same output shape; meaningfully faster with many transfers.
+- **Hoisted lookup tables** — `STATUS_BADGE_CLASSES` / `STATUS_BADGE_LABELS` / `BASIS_BADGE_CLASSES` / `BASIS_BADGE_LABELS` (LawfulBasisTracker), `RISK_BADGE_CLASSES` / `CB_STATUS_BADGE_*` (CrossBorderTransferManager), `ROPA_STATUS_BADGE_*` / `ROPA_BASIS_BADGE_LABELS` (ROPAManager) moved from inside `useCallback` bodies to module scope. Eliminates per-row object allocation on every render.
+
+Two perf items from the audit were **inspected and intentionally skipped** with documented reasons:
+
+- `useDefaultPrivacyPolicy` was already cached via a `useRef`-gated init (not a typical `useMemo` shape, but functionally equivalent — the comment at line 167 calls out the intentional semantics).
+- `ROPAManager` inline onChange closures were already paired with `useCallback`-stable `updateEditingField` / `updateControllerField` refs, so the existing setup doesn't pay the per-keystroke closure-allocation cost we'd hoped to remove. Extracting a `<FormField>` component would touch >400 lines and risk subtle behavioural change for marginal gain.
+
+### Test coverage — +25 cases
+
+Suite jumped from 1212 to **1237 / 1237 passing**. New cases target gaps the audit's B4 report flagged as critical:
+
+- **`useFocusTrap`** (7 cases, new file) — restore-focus-on-deactivation, Tab cycling forward, Shift+Tab cycling backward, onEscape, listener cleanup, `autoFocus: false`. Previously zero dedicated tests for 128 LOC of WCAG-critical focus-trap logic.
+- **`useComplianceScore`** (2 cases, new file) — memoisation by deep equality, recompute on inner-field change.
+- **`NDPRDashboard` preset** (2 cases, new file) — `ComplianceInput` → score ring; degraded input lowers score.
+- **`NDPRThemeProvider`** (2 added cases) — `mode: 'light'` sets `data-theme="light"`; empty `theme={{}}` produces no style attribute.
+- **`assessDPIARisk`** (2 added cases) — empty-risks array → low-level; all-mitigated high-risk → `canProceed: true`.
+- **`NDPRProvider`** (3 cases, new file) — `useNDPRConfig` returns provided config; `useNDPRLocale` merges partial overrides with English defaults; nested-provider innermost-wins.
+- **`preset-callbacks`** (7 cases, new file) — submit / save / complete callbacks across `NDPRConsent`, `NDPRBreachReport` (with adapter), `NDPRDPIA`, `NDPRLawfulBasis`, `NDPRCrossBorder`, `NDPRROPA`. (One preset deferred: `NDPRPrivacyPolicy.onComplete` only fires after a multi-step wizard flow with valid data — would duplicate `useAdaptivePolicyWizard`'s own tests.)
+
+### Deferred from the original 3.12.0 plan
+
+- **`/server` split into `/server/utils`, `/server/policy`, `/server/locales`.** Inspected: the 261-line `/server` re-exports translate to ~40 chunks pulled by tsup, but consumers already have narrower subpaths (`/dsr`, `/policy`, etc.) for the same use cases. The split adds 3 entry points + 3 PROBES + 3 docs entries for marginal benefit. Slated for re-evaluation in the 4.x roadmap discussion alongside the B20 strategic items.
+
+### Verification
+
+- Jest: **1237 / 1237 passing** (was 1212; +25 new tests)
+- `tsc --noEmit -p tsconfig.json` clean
+- `pnpm verify:tarball --skip-ts` clean across all 22 subpaths
+
+## [3.11.0](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.10.6...v3.11.0) (2026-05-27)
+
+Release 3 of 6 on the post-audit roadmap. Strictly additive — every change here adds to the public surface or fixes a docs lie. Existing consumers keep working without changes.
+
+### Type-export baseline — `*Props` interfaces, adapter ecosystem types, hook return types now reachable
+
+Every component's `Props` interface is now re-exported from `src/index.ts` (the default entry):
+
+`ConsentBannerProps`, `ConsentManagerProps`, `ConsentStorageProps`, `DSRRequestFormProps`, `DSRDashboardProps`, `DSRTrackerProps`, `DPIAQuestionnaireProps`, `DPIAReportProps`, `StepIndicatorProps`, `BreachReportFormProps`, `BreachRiskAssessmentProps`, `BreachNotificationManagerProps`, `RegulatoryReportGeneratorProps`, `PolicyGeneratorProps`, `PolicyPreviewProps`, `PolicyExporterProps`, `LawfulBasisTrackerProps`, `CrossBorderTransferManagerProps`, `ROPAManagerProps`.
+
+Consumers can now type-safely wrap the toolkit's components — e.g.
+
+```ts
+import type { ConsentBannerProps, NDPRThemeProvider } from '@tantainnovative/ndpr-toolkit';
+
+function MyConsentBanner(props: ConsentBannerProps & { brand?: string }) { … }
+```
+
+Adapter ecosystem types reachable too:
+- `ApiAdapterErrorContext<T>`, `ApiAdapterSuccessContext<T>`, `ApiAdapterRetryConfig`, `ApiAdapterMethod` from `/adapters` and root
+- `CookieAdapterOptions`, `StorageAdapter<T>` from `/adapters` and root
+
+DSR validator types reachable:
+- `DsrSubmissionPayload`, `DsrSubmissionValidationResult`, `ValidateDsrSubmissionOptions` from `/server` (canonical) and root
+
+Hook option/return interfaces promoted to `export interface` and re-exported through `hooks-entry.ts` (auto-flows to `/headless`):
+- `UseConsentOptions`/`Return`, `UseDSROptions`, `UseBreachOptions`, `UseDPIAOptions`, `UseLawfulBasisOptions`, `UseCrossBorderTransferOptions`, `UseComplianceScoreOptions`, `UsePrivacyPolicyOptions`.
+
+### JSDoc `@example` blocks on every public hook + adapter
+
+Added `@example` blocks to all 10 public hooks (`useConsent`, `useDSR`, `useBreach`, `useDPIA`, `useLawfulBasis`, `useCrossBorderTransfer`, `usePrivacyPolicy`, `useROPA`, `useAdaptivePolicyWizard`, `useComplianceScore`) and 5 adapters (`cookieAdapter`, `localStorageAdapter`, `sessionStorageAdapter`, `memoryAdapter`, `composeAdapters`). `useComplianceScore` previously had zero JSDoc; full block added (description + `@param` + `@returns` + `@example`).
+
+### Internal: `validateDsrSubmission` type-guard refactor
+
+Replaced the `as string` cast chain in `utils/dsr.ts` with a `isDsrPayloadRaw(payload): payload is DsrPayloadRaw` type guard. External signature unchanged. Safer narrowing; no consumer-visible difference.
+
+### Docs
+
+**9 new component pages** under `src/app/docs/components/`, all wired into the sidebar nav:
+
+- `ndpr-theme-provider`, `ndpr-provider`, `ndpr-dashboard`, `adaptive-policy-wizard`, `policy-page`, `legal-notice` (previously had no dedicated pages)
+- `lawful-basis-tracker-lite`, `cross-border-transfer-manager-lite`, `ropa-manager-lite` (Lite variants previously only mentioned inline)
+
+**Fixed broken docs** that taught fictitious symbol names:
+- 5 `useDSR()` calls without the required `requestTypes` arg, in `components/data-subject-rights/page.tsx`, `components/hooks/page.tsx`, and `guides/data-subject-requests/page.tsx`. All now show `useDSR({ requestTypes })` with the correct API.
+- `getRequestById` → `getRequest`, `filterRequestsByStatus` → `getRequestsByStatus`, `filterRequestsByType` → `getRequestsByType` (the docs were inventing names that don't exist). `deleteRequest` removed — no such function ships.
+- `onSubmit` prop on the DSR component page now typed `DSRFormSubmission`, not the fictitious `DSRFormData`.
+
+### README compact pass
+
+- Bumped version refs `v3.10.3` → `v3.11.0` (6 occurrences: header release link + 5 screenshot URL tags).
+- Replaced the 3-File Quickstart's throwaway `let store: unknown = null` API route with a clean 2-file quickstart that uses `localStorageAdapter` by default and shows `cookieAdapter` / `apiAdapter` / `composeAdapters` as opt-ins. The throwaway demo always looked unprofessional next to claims of production-readiness.
+- New **"When NOT to use this toolkit"** section between Adapters and Pluggable Storage. Honest framing: non-React stacks, banner-only use cases, GDPR-primary regimes, enterprise CMP shoppers should pick something else. Builds trust with the people who are the right fit.
+- "What's new" notice rewritten for 3.11.0 (less narrative, more skimmable).
+
+### CONTRIBUTING.md rewritten
+
+The previous file was generic boilerplate. The new one covers the practical things contributors actually need: pnpm 10 / Node ≥20 setup, repo layout (with a callout that the root `package.json` is the publish surface, not the inner one), how to run a single test, the `verify:tarball` gate, the release flow, branch conventions, patch/minor/major decision table, i18n contribution guide.
+
+### Verification
+
+- Jest: **1212 / 1212 passing** (no behaviour changes)
+- `tsc --noEmit -p tsconfig.json` — clean
+- `pnpm verify:tarball --skip-ts` — clean across all 22 subpaths
+
 ## [3.10.6](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.10.5...v3.10.6) (2026-05-27)
 
 Release 2 of 6 on the post-audit roadmap. CI / repo plumbing only — zero `dist/` changes, zero behaviour changes for consumers.

package/README.md

@@ -11,28 +11,29 @@
 
 v3 ships **zero-config presets**, **pluggable storage adapters**, **compound components**, and a **compliance score engine** — eight production-ready modules covering consent, data subject rights, DPIA, breach notification, privacy policies, lawful basis, cross-border transfers, and ROPA.
 
-**[Documentation](https://ndprtoolkit.com.ng)** | **[Live Demos](https://ndprtoolkit.com.ng/ndpr-demos)** | **[npm](https://www.npmjs.com/package/@tantainnovative/ndpr-toolkit)** | **[Blog](https://ndprtoolkit.com.ng/blog)** | **[v3.10.3 Release](https://github.com/mr-tanta/ndpr-toolkit/releases/tag/v3.10.3)**
+**[Documentation](https://ndprtoolkit.com.ng)** | **[Live Demos](https://ndprtoolkit.com.ng/ndpr-demos)** | **[npm](https://www.npmjs.com/package/@tantainnovative/ndpr-toolkit)** | **[Blog](https://ndprtoolkit.com.ng/blog)** | **[v3.11.0 Release](https://github.com/mr-tanta/ndpr-toolkit/releases/tag/v3.11.0)**
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/mr-tanta/ndpr-toolkit/tree/main/examples/nextjs-app)
 [![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/github/mr-tanta/ndpr-toolkit/main/examples/nextjs-app)
 
-> **What's new in 3.10.x:** Typed theming via `<NDPRThemeProvider>`, a `/headless` subpath alias of `/hooks` for headless-UI consumers, and a production-grade DSR backend reference at `examples/dsr-backend-prod/` (Prisma + Resend behind no-infra shims). New docs guides: [theming](https://ndprtoolkit.com.ng/docs/guides/theming), [headless](https://ndprtoolkit.com.ng/docs/guides/headless), [production-dsr-backend](https://ndprtoolkit.com.ng/docs/guides/production-dsr-backend).
+> **What's new in 3.11.0:** Every component's `Props` interface is now re-exported from the root (consumers can finally wrap toolkit components without copying types). Adapter ecosystem types (`ApiAdapterErrorContext`, `StorageAdapter<T>`, …) and DSR validator types reachable from `/server` + root. 9 new component docs pages cover `NDPRThemeProvider`, `NDPRProvider`, `NDPRDashboard`, `AdaptivePolicyWizard`, `PolicyPage`, the 3 Lite manager variants, and `LegalNotice`.
 >
-> **Upgrading from 3.7.x?** See the [3.7 → 3.10 upgrade guide](https://ndprtoolkit.com.ng/docs/guides/upgrading-3-7-to-3-10) — fully additive, no API breaks. Full changelog on [GitHub](https://github.com/mr-tanta/ndpr-toolkit/blob/main/CHANGELOG.md).
+> **3.10.x highlights:** Typed theming via `<NDPRThemeProvider>`, a `/headless` subpath alias of `/hooks`, the production-grade DSR backend reference at `examples/dsr-backend-prod/`, plus the `verify:tarball` CI gate that catches broken exports at PR time. Upgrading from 3.7.x? See the [3.7 → 3.10 upgrade guide](https://ndprtoolkit.com.ng/docs/guides/upgrading-3-7-to-3-10). Full history in the [CHANGELOG](https://github.com/mr-tanta/ndpr-toolkit/blob/main/CHANGELOG.md).
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.10.3/public/screenshots/hero.png" alt="NDPA Toolkit — NDPA Compliance Made Beautiful" width="800" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/hero.png" alt="NDPA Toolkit — NDPA Compliance Made Beautiful" width="800" />
 </p>
 
 ---
 
-## The 3-File Quickstart
+## Quickstart
 
-Three files. Full NDPA consent compliance.
+Two files. Full NDPA-compliant consent with no backend.
 
 **`app/layout.tsx`**
 ```tsx
 import { NDPRConsent } from '@tantainnovative/ndpr-toolkit/presets';
+import '@tantainnovative/ndpr-toolkit/styles';
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
@@ -46,31 +47,31 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-**`app/api/consent/route.ts`**
-```ts
-import { NextRequest, NextResponse } from 'next/server';
-
-let store: unknown = null;
+That's it — `NDPRConsent` defaults to `localStorageAdapter`, so consent persists across page loads with zero backend code.
 
-export async function GET() { return NextResponse.json(store ?? {}); }
-export async function POST(req: NextRequest) {
-  store = await req.json();
-  return NextResponse.json({ ok: true });
-}
-```
+**Want server-side persistence?** Pass any `StorageAdapter`:
 
-**Persist to your API instead of localStorage:**
 ```tsx
 import { NDPRConsent } from '@tantainnovative/ndpr-toolkit/presets';
-import { apiAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+import { cookieAdapter, apiAdapter, composeAdapters, localStorageAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
 
+// Server-readable cookie (best for SSR consent gating)
+<NDPRConsent adapter={cookieAdapter('ndpr_consent', { expires: 180 })} />
+
+// Or POST to your own backend
 <NDPRConsent adapter={apiAdapter('/api/consent')} />
+
+// Or both — fan-out writes
+<NDPRConsent adapter={composeAdapters(
+  apiAdapter('/api/consent'),
+  localStorageAdapter('ndpr_consent'),
+)} />
 ```
 
-That's it. NDPA-compliant consent with server-side persistence in under 20 lines.
+The full SSR pattern (cookie read server-side → banner hydrates already-resolved, no flash) is in the [Server-Side Storage guide](https://ndprtoolkit.com.ng/docs/guides/server-side-storage).
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.10.3/public/screenshots/consent-demo.png" alt="Consent Management Demo — interactive consent banner with state inspector" width="800" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/consent-demo.png" alt="Consent Management Demo — interactive consent banner with state inspector" width="800" />
   <br />
   <em>Interactive consent demo with configurable position, theme, storage, and real-time state inspector</em>
 </p>
@@ -304,6 +305,19 @@ import { apiAdapter, localStorageAdapter, cookieAdapter } from '@tantainnovative
 
 ---
 
+## When NOT to use this toolkit
+
+The toolkit is React-first, NDPA-specific, and built for product engineers shipping a compliant app — not a generic cookie-banner library. Pick something else if:
+
+- **You're not on React.** No Vue / Svelte / Angular bindings exist. The `/server` entry exposes framework-agnostic validators and the compliance-score engine — usable from any Node runtime — but the UI components are React-only.
+- **You only need a cookie banner**, with no DSR portal, breach reporting, DPIA, ROPA, or compliance scoring. A purpose-built consent library (Iubenda, OneTrust, Cookiebot, Osano) is a better fit and will integrate with your CMP / TCF setup. The toolkit can do the banner alone, but you'd be paying for surface you don't use.
+- **Your compliance regime is GDPR / CCPA-primary** and you don't operate under the Nigeria Data Protection Act 2023. The validators, statutory deadlines, and section citations are NDPA-specific. (NDPA + GDPR overlap a lot in practice; the toolkit doesn't pretend to be a GDPR product.)
+- **You need an enterprise consent-management platform** with audit trails, marketing-team UIs, regional CMP exports, and a vendor SLA. That's a different product category.
+
+The toolkit is what we wished existed when building Nigerian SaaS apps in 2025 and need NDPA components that don't fight the rest of the stack. If that's your shape, read on.
+
+---
+
 ## Pluggable Storage
 
 Every stateful component accepts an `adapter` prop. Built-in adapters ship out of the box.
@@ -434,13 +448,13 @@ Every module has an interactive demo. No signup, no setup — try them instantly
 
 <p align="center">
   <a href="https://ndprtoolkit.com.ng/ndpr-demos">
-    <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.10.3/public/screenshots/demos-overview.png" alt="8 interactive live demos — zero setup required" width="800" />
+    <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/demos-overview.png" alt="8 interactive live demos — zero setup required" width="800" />
   </a>
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.10.3/public/screenshots/dsr-demo.png" alt="Data Subject Rights — 8 rights with request tracking" width="400" />
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.10.3/public/screenshots/breach-demo.png" alt="Breach Notification — 72-hour countdown with step-by-step workflow" width="400" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/dsr-demo.png" alt="Data Subject Rights — 8 rights with request tracking" width="400" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/breach-demo.png" alt="Breach Notification — 72-hour countdown with step-by-step workflow" width="400" />
 </p>
 
 <p align="center">

package/dist/adapters.d.mts

@@ -32,7 +32,7 @@
  */
 export declare function apiAdapter<T = unknown>(endpoint: string, options?: ApiAdapterOptions<T>): StorageAdapter<T>;
 
-declare interface ApiAdapterErrorContext<T = unknown> {
+export declare interface ApiAdapterErrorContext<T = unknown> {
     /** Which adapter operation triggered this — `load`, `save`, or `remove`. */
     method: ApiAdapterMethod;
     /** The endpoint URL that failed. */
@@ -49,7 +49,7 @@ declare interface ApiAdapterErrorContext<T = unknown> {
     attempt: number;
 }
 
-declare type ApiAdapterMethod = 'load' | 'save' | 'remove';
+export declare type ApiAdapterMethod = 'load' | 'save' | 'remove';
 
 export declare interface ApiAdapterOptions<T = unknown> {
     /**
@@ -106,7 +106,7 @@ export declare interface ApiAdapterOptions<T = unknown> {
     fetchInit?: Omit<RequestInit, 'method' | 'headers' | 'body' | 'credentials'>;
 }
 
-declare interface ApiAdapterRetryConfig {
+export declare interface ApiAdapterRetryConfig {
     /**
      * Number of additional attempts after the initial request. Defaults to 0
      * (no retries). e.g. `attempts: 2` means up to 3 total requests.
@@ -125,7 +125,7 @@ declare interface ApiAdapterRetryConfig {
     shouldRetry?: (ctx: ApiAdapterErrorContext<unknown>) => boolean;
 }
 
-declare interface ApiAdapterSuccessContext<T = unknown> {
+export declare interface ApiAdapterSuccessContext<T = unknown> {
     /** Which adapter operation succeeded — `load`, `save`, or `remove`. */
     method: ApiAdapterMethod;
     /** The endpoint URL. */
@@ -138,8 +138,51 @@ declare interface ApiAdapterSuccessContext<T = unknown> {
     payload?: T;
 }
 
+/**
+ * Compose a primary adapter with one or more secondary adapters. Reads
+ * always go to the primary; writes (`save` / `remove`) fan out to the
+ * primary first, then each secondary. Secondary failures are logged but
+ * never propagated.
+ *
+ * Useful for shadowing localStorage to an API endpoint, mirroring consent
+ * to a cookie for SSR, or building offline-first sync.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   composeAdapters,
+ *   localStorageAdapter,
+ *   apiAdapter,
+ * } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = composeAdapters(
+ *   localStorageAdapter('ndpr_consent'),
+ *   apiAdapter('/api/consent'),
+ * );
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function composeAdapters<T = unknown>(primary: StorageAdapter<T>, ...secondaries: StorageAdapter<T>[]): StorageAdapter<T>;
 
+/**
+ * Storage adapter backed by a browser cookie. Useful for consent state that
+ * needs to be shared with server-side rendering, or for cross-subdomain
+ * persistence via the `domain` option.
+ *
+ * @example
+ * ```ts
+ * import { cookieAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = cookieAdapter('ndpr_consent', {
+ *   domain: '.example.com',
+ *   sameSite: 'Lax',
+ *   expires: 180,
+ * });
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function cookieAdapter<T = unknown>(key: string, options?: CookieAdapterOptions): StorageAdapter<T>;
 
 export declare interface CookieAdapterOptions {
@@ -150,10 +193,53 @@ export declare interface CookieAdapterOptions {
     sameSite?: 'Strict' | 'Lax' | 'None';
 }
 
+/**
+ * Storage adapter backed by `window.localStorage`. The default adapter used
+ * by every hook in the toolkit when no `adapter` prop is supplied.
+ *
+ * Safe to import server-side — every method short-circuits when
+ * `window` is undefined, so calling `load()` on the server returns `null`.
+ *
+ * @example
+ * ```ts
+ * import { localStorageAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = localStorageAdapter('ndpr_consent');
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function localStorageAdapter<T = unknown>(key: string): StorageAdapter<T>;
 
+/**
+ * Storage adapter backed by an in-memory value. Useful in tests, Storybook,
+ * SSR previews, or anywhere persistence across reloads is undesirable.
+ *
+ * @example
+ * ```ts
+ * import { memoryAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = memoryAdapter({ consents: {}, version: '1.0' });
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function memoryAdapter<T = unknown>(initialData?: T): StorageAdapter<T>;
 
+/**
+ * Storage adapter backed by `window.sessionStorage`. Data is scoped to the
+ * current tab and discarded when the tab closes — useful for consent
+ * choices that should not survive a fresh session.
+ *
+ * @example
+ * ```ts
+ * import { sessionStorageAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = sessionStorageAdapter('ndpr_consent');
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function sessionStorageAdapter<T = unknown>(key: string): StorageAdapter<T>;
 
 export declare interface StorageAdapter<T = unknown> {

package/dist/adapters.d.ts

@@ -32,7 +32,7 @@
  */
 export declare function apiAdapter<T = unknown>(endpoint: string, options?: ApiAdapterOptions<T>): StorageAdapter<T>;
 
-declare interface ApiAdapterErrorContext<T = unknown> {
+export declare interface ApiAdapterErrorContext<T = unknown> {
     /** Which adapter operation triggered this — `load`, `save`, or `remove`. */
     method: ApiAdapterMethod;
     /** The endpoint URL that failed. */
@@ -49,7 +49,7 @@ declare interface ApiAdapterErrorContext<T = unknown> {
     attempt: number;
 }
 
-declare type ApiAdapterMethod = 'load' | 'save' | 'remove';
+export declare type ApiAdapterMethod = 'load' | 'save' | 'remove';
 
 export declare interface ApiAdapterOptions<T = unknown> {
     /**
@@ -106,7 +106,7 @@ export declare interface ApiAdapterOptions<T = unknown> {
     fetchInit?: Omit<RequestInit, 'method' | 'headers' | 'body' | 'credentials'>;
 }
 
-declare interface ApiAdapterRetryConfig {
+export declare interface ApiAdapterRetryConfig {
     /**
      * Number of additional attempts after the initial request. Defaults to 0
      * (no retries). e.g. `attempts: 2` means up to 3 total requests.
@@ -125,7 +125,7 @@ declare interface ApiAdapterRetryConfig {
     shouldRetry?: (ctx: ApiAdapterErrorContext<unknown>) => boolean;
 }
 
-declare interface ApiAdapterSuccessContext<T = unknown> {
+export declare interface ApiAdapterSuccessContext<T = unknown> {
     /** Which adapter operation succeeded — `load`, `save`, or `remove`. */
     method: ApiAdapterMethod;
     /** The endpoint URL. */
@@ -138,8 +138,51 @@ declare interface ApiAdapterSuccessContext<T = unknown> {
     payload?: T;
 }
 
+/**
+ * Compose a primary adapter with one or more secondary adapters. Reads
+ * always go to the primary; writes (`save` / `remove`) fan out to the
+ * primary first, then each secondary. Secondary failures are logged but
+ * never propagated.
+ *
+ * Useful for shadowing localStorage to an API endpoint, mirroring consent
+ * to a cookie for SSR, or building offline-first sync.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   composeAdapters,
+ *   localStorageAdapter,
+ *   apiAdapter,
+ * } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = composeAdapters(
+ *   localStorageAdapter('ndpr_consent'),
+ *   apiAdapter('/api/consent'),
+ * );
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function composeAdapters<T = unknown>(primary: StorageAdapter<T>, ...secondaries: StorageAdapter<T>[]): StorageAdapter<T>;
 
+/**
+ * Storage adapter backed by a browser cookie. Useful for consent state that
+ * needs to be shared with server-side rendering, or for cross-subdomain
+ * persistence via the `domain` option.
+ *
+ * @example
+ * ```ts
+ * import { cookieAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = cookieAdapter('ndpr_consent', {
+ *   domain: '.example.com',
+ *   sameSite: 'Lax',
+ *   expires: 180,
+ * });
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function cookieAdapter<T = unknown>(key: string, options?: CookieAdapterOptions): StorageAdapter<T>;
 
 export declare interface CookieAdapterOptions {
@@ -150,10 +193,53 @@ export declare interface CookieAdapterOptions {
     sameSite?: 'Strict' | 'Lax' | 'None';
 }
 
+/**
+ * Storage adapter backed by `window.localStorage`. The default adapter used
+ * by every hook in the toolkit when no `adapter` prop is supplied.
+ *
+ * Safe to import server-side — every method short-circuits when
+ * `window` is undefined, so calling `load()` on the server returns `null`.
+ *
+ * @example
+ * ```ts
+ * import { localStorageAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = localStorageAdapter('ndpr_consent');
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function localStorageAdapter<T = unknown>(key: string): StorageAdapter<T>;
 
+/**
+ * Storage adapter backed by an in-memory value. Useful in tests, Storybook,
+ * SSR previews, or anywhere persistence across reloads is undesirable.
+ *
+ * @example
+ * ```ts
+ * import { memoryAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = memoryAdapter({ consents: {}, version: '1.0' });
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function memoryAdapter<T = unknown>(initialData?: T): StorageAdapter<T>;
 
+/**
+ * Storage adapter backed by `window.sessionStorage`. Data is scoped to the
+ * current tab and discarded when the tab closes — useful for consent
+ * choices that should not survive a fresh session.
+ *
+ * @example
+ * ```ts
+ * import { sessionStorageAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * const adapter = sessionStorageAdapter('ndpr_consent');
+ * useConsent({ options, adapter });
+ * ```
+ */
 export declare function sessionStorageAdapter<T = unknown>(key: string): StorageAdapter<T>;
 
 export declare interface StorageAdapter<T = unknown> {

package/dist/breach.d.mts

@@ -770,7 +770,19 @@ export declare interface StorageAdapter<T = unknown> {
 }
 
 /**
- * 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;
 

package/dist/breach.d.ts

@@ -770,7 +770,19 @@ export declare interface StorageAdapter<T = unknown> {
 }
 
 /**
- * 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;
 

package/dist/breach.js

@@ -1,2 +1,2 @@
 "use client";
-'use strict';var chunkPGI2LM6P_js=require('./chunk-PGI2LM6P.js'),chunkO2RDZGM2_js=require('./chunk-O2RDZGM2.js'),chunkVJTQXVAF_js=require('./chunk-VJTQXVAF.js'),chunk3YTAOT5O_js=require('./chunk-3YTAOT5O.js');require('./chunk-UXUMYP4L.js'),require('./chunk-NDKDKDDX.js'),require('./chunk-WKTKTLMF.js'),require('./chunk-ZVOIR4QH.js'),require('./chunk-AME4HJR4.js'),require('./chunk-VWED6UTN.js');var chunkRFPLZDIO_js=require('./chunk-RFPLZDIO.js'),react=require('react'),jsxRuntime=require('react/jsx-runtime');var c=react.createContext(null);function P(){let e=react.useContext(c);if(!e)throw new Error("Breach compound components must be wrapped in <Breach.Provider>. Example: <Breach.Provider categories={...}><Breach.ReportForm /></Breach.Provider>");return e}var p=({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u,children:d})=>{let y=chunkVJTQXVAF_js.a({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u}),l=chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},y),{categories:e});return jsxRuntime.jsx(c.Provider,{value:l,children:d})};var A={Provider:p,ReportForm:chunkO2RDZGM2_js.a,RiskAssessment:chunkPGI2LM6P_js.a,NotificationManager:chunkPGI2LM6P_js.b,ReportGenerator:chunkPGI2LM6P_js.c};Object.defineProperty(exports,"BreachNotificationManager",{enumerable:true,get:function(){return chunkPGI2LM6P_js.b}});Object.defineProperty(exports,"BreachRiskAssessment",{enumerable:true,get:function(){return chunkPGI2LM6P_js.a}});Object.defineProperty(exports,"RegulatoryReportGenerator",{enumerable:true,get:function(){return chunkPGI2LM6P_js.c}});Object.defineProperty(exports,"BreachReportForm",{enumerable:true,get:function(){return chunkO2RDZGM2_js.a}});Object.defineProperty(exports,"useBreach",{enumerable:true,get:function(){return chunkVJTQXVAF_js.a}});Object.defineProperty(exports,"calculateBreachSeverity",{enumerable:true,get:function(){return chunk3YTAOT5O_js.a}});exports.Breach=A;exports.BreachProvider=p;exports.useBreachCompound=P;
+'use strict';var chunkYK22SYCT_js=require('./chunk-YK22SYCT.js'),chunkVUFTRKKC_js=require('./chunk-VUFTRKKC.js'),chunkEHQVTFYO_js=require('./chunk-EHQVTFYO.js'),chunk3YTAOT5O_js=require('./chunk-3YTAOT5O.js');require('./chunk-UXUMYP4L.js'),require('./chunk-NDKDKDDX.js'),require('./chunk-WKTKTLMF.js'),require('./chunk-ZVOIR4QH.js'),require('./chunk-AME4HJR4.js'),require('./chunk-VWED6UTN.js');var chunkRFPLZDIO_js=require('./chunk-RFPLZDIO.js'),react=require('react'),jsxRuntime=require('react/jsx-runtime');var c=react.createContext(null);function P(){let e=react.useContext(c);if(!e)throw new Error("Breach compound components must be wrapped in <Breach.Provider>. Example: <Breach.Provider categories={...}><Breach.ReportForm /></Breach.Provider>");return e}var p=({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u,children:d})=>{let y=chunkEHQVTFYO_js.a({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u}),l=chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},y),{categories:e});return jsxRuntime.jsx(c.Provider,{value:l,children:d})};var A={Provider:p,ReportForm:chunkVUFTRKKC_js.a,RiskAssessment:chunkYK22SYCT_js.a,NotificationManager:chunkYK22SYCT_js.b,ReportGenerator:chunkYK22SYCT_js.c};Object.defineProperty(exports,"BreachNotificationManager",{enumerable:true,get:function(){return chunkYK22SYCT_js.b}});Object.defineProperty(exports,"BreachRiskAssessment",{enumerable:true,get:function(){return chunkYK22SYCT_js.a}});Object.defineProperty(exports,"RegulatoryReportGenerator",{enumerable:true,get:function(){return chunkYK22SYCT_js.c}});Object.defineProperty(exports,"BreachReportForm",{enumerable:true,get:function(){return chunkVUFTRKKC_js.a}});Object.defineProperty(exports,"useBreach",{enumerable:true,get:function(){return chunkEHQVTFYO_js.a}});Object.defineProperty(exports,"calculateBreachSeverity",{enumerable:true,get:function(){return chunk3YTAOT5O_js.a}});exports.Breach=A;exports.BreachProvider=p;exports.useBreachCompound=P;

package/dist/breach.mjs

@@ -1,2 +1,2 @@
 "use client";
-import {c as c$1,b,a}from'./chunk-X3GCGC3H.mjs';export{b as BreachNotificationManager,a as BreachRiskAssessment,c as RegulatoryReportGenerator}from'./chunk-X3GCGC3H.mjs';import {a as a$1}from'./chunk-KY6WYHWB.mjs';export{a as BreachReportForm}from'./chunk-KY6WYHWB.mjs';import {a as a$2}from'./chunk-3HOXQNCH.mjs';export{a as useBreach}from'./chunk-3HOXQNCH.mjs';export{a as calculateBreachSeverity}from'./chunk-WTGKZX7J.mjs';import'./chunk-EWVK45Z3.mjs';import'./chunk-25TNTLHJ.mjs';import'./chunk-RBMLGRDN.mjs';import'./chunk-ITCY2Z66.mjs';import'./chunk-SFGW37LE.mjs';import'./chunk-DBZSN4WP.mjs';import {b as b$1,a as a$3}from'./chunk-ZJYULEER.mjs';import {createContext,useContext}from'react';import {jsx}from'react/jsx-runtime';var c=createContext(null);function P(){let e=useContext(c);if(!e)throw new Error("Breach compound components must be wrapped in <Breach.Provider>. Example: <Breach.Provider categories={...}><Breach.ReportForm /></Breach.Provider>");return e}var p=({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u,children:d})=>{let y=a$2({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u}),l=b$1(a$3({},y),{categories:e});return jsx(c.Provider,{value:l,children:d})};var A={Provider:p,ReportForm:a$1,RiskAssessment:a,NotificationManager:b,ReportGenerator:c$1};export{A as Breach,p as BreachProvider,P as useBreachCompound};
+import {c as c$1,b,a}from'./chunk-JYZOKO2W.mjs';export{b as BreachNotificationManager,a as BreachRiskAssessment,c as RegulatoryReportGenerator}from'./chunk-JYZOKO2W.mjs';import {a as a$1}from'./chunk-TN4TH3CT.mjs';export{a as BreachReportForm}from'./chunk-TN4TH3CT.mjs';import {a as a$2}from'./chunk-RFXGD5NE.mjs';export{a as useBreach}from'./chunk-RFXGD5NE.mjs';export{a as calculateBreachSeverity}from'./chunk-WTGKZX7J.mjs';import'./chunk-EWVK45Z3.mjs';import'./chunk-25TNTLHJ.mjs';import'./chunk-RBMLGRDN.mjs';import'./chunk-ITCY2Z66.mjs';import'./chunk-SFGW37LE.mjs';import'./chunk-DBZSN4WP.mjs';import {b as b$1,a as a$3}from'./chunk-ZJYULEER.mjs';import {createContext,useContext}from'react';import {jsx}from'react/jsx-runtime';var c=createContext(null);function P(){let e=useContext(c);if(!e)throw new Error("Breach compound components must be wrapped in <Breach.Provider>. Example: <Breach.Provider categories={...}><Breach.ReportForm /></Breach.Provider>");return e}var p=({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u,children:d})=>{let y=a$2({categories:e,adapter:m,storageKey:h,useLocalStorage:B,initialReports:f,onReport:R,onAssessment:x,onNotification:u}),l=b$1(a$3({},y),{categories:e});return jsx(c.Provider,{value:l,children:d})};var A={Provider:p,ReportForm:a$1,RiskAssessment:a,NotificationManager:b,ReportGenerator:c$1};export{A as Breach,p as BreachProvider,P as useBreachCompound};