@tantainnovative/ndpr-toolkit 3.4.1 → 3.5.1

package/dist/unstyled.d.ts

@@ -1,55 +1,523 @@
-import React__default from 'react';
-import { c as ConsentBannerProps } from './ConsentBanner-VqIPophc.js';
-export { C as ConsentAnalyticsEvent, b as ConsentBannerClassNames } from './ConsentBanner-VqIPophc.js';
-import { b as ConsentManagerProps } from './ConsentManager-CQ2IZtUU.js';
-export { a as ConsentManagerClassNames } from './ConsentManager-CQ2IZtUU.js';
-import { c as DSRRequestFormProps } from './DSRRequestForm-D8rPTNmU.js';
-export { b as DSRRequestFormClassNames } from './DSRRequestForm-D8rPTNmU.js';
-import './consent-CmVzqZUk.js';
-import './dsr-yKbqX531.js';
-
-/**
- * Unstyled entry — design-system-friendly component variants.
- *
- * Components imported from this subpath default `unstyled` to `true`,
- * which strips every default class name from the rendered markup.
- * Consumers using their own design system (Tailwind, Mantine, Chakra,
- * shadcn, raw CSS) get logic + accessibility + semantic structure
- * without any pre-applied visual styling.
- *
- * Markup, ARIA attributes, focus management, keyboard handling, and the
- * `data-ndpr-component` data attributes are all preserved — those are
- * part of the contract, not styling.
- *
- * @example
- * ```tsx
- * // app/cookie-banner.tsx
- * import { ConsentBanner } from '@tantainnovative/ndpr-toolkit/unstyled';
- *
- * export function CookieBanner() {
- *   return (
- *     <ConsentBanner
- *       options={[]}
- *       onSave={() => {}}
- *       classNames={{
- *         root: 'fixed bottom-0 inset-x-0 bg-white p-6 shadow-2xl',
- *         title: 'text-xl font-bold mb-2',
- *         buttonGroup: 'flex gap-2 mt-4',
- *         acceptButton: 'btn-primary',
- *         rejectButton: 'btn-secondary',
- *       }}
- *     />
- *   );
- * }
- * ```
- *
- * For components not yet migrated to the BEM stylesheet (DPIA, Breach,
- * ROPA, etc.), import them from their normal subpath and pass
- * `unstyled` manually if available — the migration completes in 3.5.x.
- */
-
-declare const ConsentBanner: React__default.FC<ConsentBannerProps>;
-declare const ConsentManager: React__default.FC<ConsentManagerProps>;
-declare const DSRRequestForm: React__default.FC<DSRRequestFormProps>;
-
-export { ConsentBanner, ConsentBannerProps, ConsentManager, ConsentManagerProps, DSRRequestForm, DSRRequestFormProps };
+import React__default from 'react';
+
+export declare interface ConsentAnalyticsEvent {
+    action: 'shown' | 'accepted_all' | 'rejected_all' | 'customized' | 'dismissed';
+    timestamp: number;
+    version: string;
+    categories?: Record<string, boolean>;
+}
+
+/**
+ * Unstyled entry — design-system-friendly component variants.
+ *
+ * Components imported from this subpath default `unstyled` to `true`,
+ * which strips every default class name from the rendered markup.
+ * Consumers using their own design system (Tailwind, Mantine, Chakra,
+ * shadcn, raw CSS) get logic + accessibility + semantic structure
+ * without any pre-applied visual styling.
+ *
+ * Markup, ARIA attributes, focus management, keyboard handling, and the
+ * `data-ndpr-component` data attributes are all preserved — those are
+ * part of the contract, not styling.
+ *
+ * @example
+ * ```tsx
+ * // app/cookie-banner.tsx
+ * import { ConsentBanner } from '@tantainnovative/ndpr-toolkit/unstyled';
+ *
+ * export function CookieBanner() {
+ *   return (
+ *     <ConsentBanner
+ *       options={[]}
+ *       onSave={() => {}}
+ *       classNames={{
+ *         root: 'fixed bottom-0 inset-x-0 bg-white p-6 shadow-2xl',
+ *         title: 'text-xl font-bold mb-2',
+ *         buttonGroup: 'flex gap-2 mt-4',
+ *         acceptButton: 'btn-primary',
+ *         rejectButton: 'btn-secondary',
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * For components not yet migrated to the BEM stylesheet (DPIA, Breach,
+ * ROPA, etc.), import them from their normal subpath and pass
+ * `unstyled` manually if available — the migration completes in 3.5.x.
+ */
+export declare const ConsentBanner: React__default.FC<ConsentBannerProps>;
+
+export declare interface ConsentBannerClassNames {
+    root?: string;
+    container?: string;
+    title?: string;
+    description?: string;
+    optionsList?: string;
+    optionItem?: string;
+    optionCheckbox?: string;
+    optionLabel?: string;
+    optionDescription?: string;
+    buttonGroup?: string;
+    acceptButton?: string;
+    rejectButton?: string;
+    customizeButton?: string;
+    saveButton?: string;
+    customizePanel?: string;
+    selectAllButton?: string;
+    /** Alias for acceptButton */
+    primaryButton?: string;
+    /** Alias for rejectButton */
+    secondaryButton?: string;
+}
+
+export declare interface ConsentBannerProps {
+    /**
+     * Array of consent options to display
+     */
+    options: ConsentOption[];
+    /**
+     * Callback function called when user saves their consent choices
+     */
+    onSave: (settings: ConsentSettings) => void;
+    /**
+     * Title displayed on the banner
+     * @default "We Value Your Privacy"
+     */
+    title?: string;
+    /**
+     * Description text displayed on the banner
+     * @default "We use cookies and similar technologies to provide our services and enhance your experience. Your consent is collected in accordance with NDPA Sections 25-26."
+     */
+    description?: string;
+    /**
+     * Text for the accept all button
+     * @default "Accept All"
+     */
+    acceptAllButtonText?: string;
+    /**
+     * Text for the reject all button
+     * @default "Reject All"
+     */
+    rejectAllButtonText?: string;
+    /**
+     * Text for the customize button
+     * @default "Customize"
+     */
+    customizeButtonText?: string;
+    /**
+     * Text for the save button
+     * @default "Save Preferences"
+     */
+    saveButtonText?: string;
+    /**
+     * Position of the banner.
+     * 'top', 'bottom', and 'center' render via a portal to document.body
+     * with fixed positioning so the banner overlays the page.
+     * 'inline' renders in the normal DOM tree without a portal.
+     * @default "bottom"
+     */
+    position?: 'top' | 'bottom' | 'center' | 'inline';
+    /**
+     * Visual treatment.
+     * - 'bar'   (default): full-width strip pinned to the edge.
+     * - 'card'  : bounded floating card with rounded corners and a margin
+     *             from the screen edges. Pairs well with `position="bottom"`.
+     * - 'modal' : centered card with a backdrop overlay. Forces center
+     *             placement regardless of `position`.
+     * @default "bar"
+     */
+    variant?: 'bar' | 'card' | 'modal';
+    /**
+     * z-index applied to the fixed-position banner.
+     * Ignored when position is 'inline'.
+     * @default 9999
+     */
+    zIndex?: number;
+    /**
+     * Version of the consent form
+     * @default "1.0"
+     */
+    version?: string;
+    /**
+     * Whether to show the banner
+     * If not provided, the banner will be shown if no consent has been saved
+     */
+    show?: boolean;
+    /**
+     * Storage key for consent settings
+     * @default "ndpr_consent"
+     */
+    storageKey?: string;
+    /**
+     * Whether the banner manages its own localStorage persistence.
+     * Set to false when an external storage mechanism (e.g., ConsentStorage)
+     * is responsible for persisting consent settings under the same key.
+     * This avoids race conditions where two writers target the same storage key.
+     * @default true
+     */
+    manageStorage?: boolean;
+    /**
+     * Custom CSS class for the banner
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the buttons
+     */
+    buttonClassName?: string;
+    /**
+     * Custom CSS class for the primary button
+     */
+    primaryButtonClassName?: string;
+    /**
+     * Custom CSS class for the secondary button
+     */
+    secondaryButtonClassName?: string;
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     * Takes priority over buttonClassName / primaryButtonClassName / secondaryButtonClassName.
+     */
+    classNames?: ConsentBannerClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+    /**
+     * Optional analytics callback fired on each user interaction.
+     * Called when the banner is shown, accepted, rejected, customized, or dismissed.
+     */
+    onAnalytics?: (event: ConsentAnalyticsEvent) => void;
+}
+
+export declare const ConsentManager: React__default.FC<ConsentManagerProps>;
+
+export declare interface ConsentManagerClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    description?: string;
+    optionsList?: string;
+    optionItem?: string;
+    toggle?: string;
+    saveButton?: string;
+    resetButton?: string;
+    /** Alias for saveButton */
+    primaryButton?: string;
+    /** Alias for resetButton */
+    secondaryButton?: string;
+}
+
+export declare interface ConsentManagerProps {
+    /**
+     * Array of consent options to display
+     */
+    options: ConsentOption[];
+    /**
+     * Current consent settings
+     */
+    settings?: ConsentSettings;
+    /**
+     * Callback function called when user saves their consent choices
+     */
+    onSave: (settings: ConsentSettings) => void;
+    /**
+     * Title displayed in the manager
+     * @default "Manage Your Privacy Settings"
+     */
+    title?: string;
+    /**
+     * Description text displayed in the manager
+     * @default "Update your consent preferences at any time. Required cookies cannot be disabled as they are necessary for the website to function. Consent management is provided in accordance with NDPA Sections 25-26."
+     */
+    description?: string;
+    /**
+     * Text for the save button
+     * @default "Save Preferences"
+     */
+    saveButtonText?: string;
+    /**
+     * Text for the reset button
+     * @default "Reset to Defaults"
+     */
+    resetButtonText?: string;
+    /**
+     * Version of the consent form
+     * @default "1.0"
+     */
+    version?: string;
+    /**
+     * Custom CSS class for the manager
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the buttons
+     */
+    buttonClassName?: string;
+    /**
+     * Custom CSS class for the primary button
+     */
+    primaryButtonClassName?: string;
+    /**
+     * Custom CSS class for the secondary button
+     */
+    secondaryButtonClassName?: string;
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     * Takes priority over buttonClassName / primaryButtonClassName / secondaryButtonClassName.
+     */
+    classNames?: ConsentManagerClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+    /**
+     * Whether to show a success message after saving
+     * @default true
+     */
+    showSuccessMessage?: boolean;
+    /**
+     * Success message to display after saving
+     * @default "Your preferences have been saved."
+     */
+    successMessage?: string;
+    /**
+     * Duration to show the success message (in milliseconds)
+     * @default 3000
+     */
+    successMessageDuration?: number;
+}
+
+/**
+ * Consent types aligned with NDPA 2023 Section 25-26
+ * Consent must be freely given, specific, informed, and unambiguous
+ */
+/**
+ * Represents a consent option that can be presented to users
+ */
+declare interface ConsentOption {
+    /** Unique identifier for the consent option */
+    id: string;
+    /** Display label for the consent option */
+    label: string;
+    /** Detailed description of what this consent option covers */
+    description: string;
+    /** Whether this consent option is required (cannot be declined) */
+    required: boolean;
+    /**
+     * The specific purpose for which data will be processed
+     * NDPA Section 25(2) requires consent to be specific to each purpose
+     */
+    purpose: string;
+    /**
+     * Default state of the consent option
+     * @default false
+     */
+    defaultValue?: boolean;
+    /**
+     * Categories of personal data covered by this consent option
+     */
+    dataCategories?: string[];
+}
+
+/**
+ * Represents the user's consent settings
+ */
+declare interface ConsentSettings {
+    /** Map of consent option IDs to boolean values indicating consent status */
+    consents: Record<string, boolean>;
+    /** Timestamp when consent was last updated */
+    timestamp: number;
+    /** Version of the consent form that was accepted */
+    version: string;
+    /** Method used to collect consent (e.g., "banner", "settings", "api") */
+    method: string;
+    /** Whether the user has actively made a choice (as opposed to default settings) */
+    hasInteracted: boolean;
+    /**
+     * The lawful basis under which processing is conducted
+     * Required by NDPA Section 25(1)
+     */
+    lawfulBasis?: LawfulBasisType;
+}
+
+/**
+ * Represents the data submitted by the DSR request form.
+ */
+declare interface DSRFormSubmission {
+    /** The selected request type identifier */
+    requestType: string;
+    /** Data subject personal information */
+    dataSubject: {
+        fullName: string;
+        email: string;
+        phone?: string;
+        identifierType: string;
+        identifierValue: string;
+    };
+    /** Additional information provided for the selected request type */
+    additionalInfo?: Record<string, string | number | boolean | null>;
+    /** Timestamp (ms) when the form was submitted */
+    submittedAt: number;
+}
+
+export declare const DSRRequestForm: React__default.FC<DSRRequestFormProps>;
+
+export declare interface DSRRequestFormClassNames {
+    root?: string;
+    title?: string;
+    description?: string;
+    form?: string;
+    fieldGroup?: string;
+    label?: string;
+    input?: string;
+    select?: string;
+    textarea?: string;
+    submitButton?: string;
+    /** Alias for submitButton */
+    primaryButton?: string;
+    successMessage?: string;
+    /** Custom class applied when isSubmitting is true (e.g. a loading overlay) */
+    loadingOverlay?: string;
+}
+
+export declare interface DSRRequestFormProps {
+    /**
+     * Array of request types that can be submitted
+     */
+    requestTypes: RequestType[];
+    /**
+     * Callback function called when form is submitted
+     */
+    onSubmit: (data: DSRFormSubmission) => void;
+    /**
+     * Callback function called when form validation fails
+     */
+    onValidationError?: (errors: Record<string, string>) => void;
+    /**
+     * Title displayed on the form
+     * @default "Submit a Data Subject Request"
+     */
+    title?: string;
+    /**
+     * Description text displayed on the form
+     * @default "Use this form to exercise your rights under the Nigeria Data Protection Act (NDPA), Part IV, Sections 29-36."
+     */
+    description?: string;
+    /**
+     * Text for the submit button
+     * @default "Submit Request"
+     */
+    submitButtonText?: string;
+    /**
+     * Custom CSS class for the form
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the submit button
+     */
+    buttonClassName?: string;
+    /**
+     * Whether to show a confirmation message after submission
+     * @default true
+     */
+    showConfirmation?: boolean;
+    /**
+     * Confirmation message to display after submission
+     * @default "Your request has been submitted successfully. You will receive a confirmation email shortly."
+     */
+    confirmationMessage?: string;
+    /**
+     * Whether to require identity verification
+     * @default true
+     */
+    requireIdentityVerification?: boolean;
+    /**
+     * Types of identifiers accepted for verification
+     * @default ["email", "account", "customer_id"]
+     */
+    identifierTypes?: Array<{
+        id: string;
+        label: string;
+    }>;
+    /**
+     * Whether to collect additional contact information
+     * @default true
+     */
+    collectAdditionalContact?: boolean;
+    /**
+     * Custom labels for form fields
+     */
+    labels?: {
+        name?: string;
+        email?: string;
+        requestType?: string;
+        description?: string;
+        submit?: string;
+    };
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     */
+    classNames?: DSRRequestFormClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+    /**
+     * Whether the form is currently submitting.
+     * When true, the submit button is disabled and shows "Submitting..." text.
+     */
+    isSubmitting?: boolean;
+    /**
+     * Default values to pre-fill form fields.
+     * Useful for editing existing requests or pre-populating known data.
+     */
+    defaultValues?: Partial<DSRFormSubmission>;
+    /**
+     * Callback fired when the form is reset via the Reset button.
+     * To fully remount the component (clearing all internal state),
+     * change the `key` prop from the parent.
+     */
+    onReset?: () => void;
+}
+
+/**
+ * Lawful basis for processing personal data per NDPA Section 25(1)
+ */
+declare type LawfulBasisType = 'consent' | 'contract' | 'legal_obligation' | 'vital_interests' | 'public_interest' | 'legitimate_interests';
+
+/**
+ * Represents a type of data subject request (detailed configuration)
+ */
+declare interface RequestType {
+    /** Unique identifier for the request type */
+    id: string;
+    /** Display name for the request type */
+    name: string;
+    /** Description of what this request type entails */
+    description: string;
+    /**
+     * NDPA section reference (e.g., "Section 30" for access requests)
+     */
+    ndpaSection?: string;
+    /**
+     * Estimated time to fulfill this type of request (in days)
+     * NDPA requires response within 30 days
+     */
+    estimatedCompletionTime: number;
+    /** Whether additional information is required for this request type */
+    requiresAdditionalInfo: boolean;
+    /** Custom fields required for this request type */
+    additionalFields?: Array<{
+        id: string;
+        label: string;
+        type: 'text' | 'textarea' | 'select' | 'checkbox' | 'file';
+        options?: string[];
+        required: boolean;
+        placeholder?: string;
+    }>;
+}
+
+export { }

package/dist/unstyled.js

@@ -1,3 +1,3 @@
 "use client";
-'use strict';var chunkRLYTX3MM_js=require('./chunk-RLYTX3MM.js'),chunkSUEGUY35_js=require('./chunk-SUEGUY35.js'),chunkZPKVLTSX_js=require('./chunk-ZPKVLTSX.js');require('./chunk-I54CDQGN.js'),require('./chunk-E64TU6IU.js');var chunkMQFZHA2D_js=require('./chunk-MQFZHA2D.js'),P=require('react');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var P__default=/*#__PURE__*/_interopDefault(P);function e(C,R){let n=d=>{var s=d,{unstyled:l=true}=s,c=chunkMQFZHA2D_js.c(s,["unstyled"]);return P__default.default.createElement(C,chunkMQFZHA2D_js.b(chunkMQFZHA2D_js.a({},c),{unstyled:l}))};return n.displayName=R,n}var u=e(chunkSUEGUY35_js.a,"UnstyledConsentBanner"),y=e(chunkRLYTX3MM_js.a,"UnstyledConsentManager"),S=e(chunkZPKVLTSX_js.a,"UnstyledDSRRequestForm");exports.ConsentBanner=u;exports.ConsentManager=y;exports.DSRRequestForm=S;//# sourceMappingURL=unstyled.js.map
+'use strict';var chunkRLYTX3MM_js=require('./chunk-RLYTX3MM.js'),chunkXIM7KMD6_js=require('./chunk-XIM7KMD6.js'),chunkZPKVLTSX_js=require('./chunk-ZPKVLTSX.js');require('./chunk-I54CDQGN.js'),require('./chunk-E64TU6IU.js');var chunkMQFZHA2D_js=require('./chunk-MQFZHA2D.js'),P=require('react');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var P__default=/*#__PURE__*/_interopDefault(P);function e(C,R){let n=d=>{var s=d,{unstyled:l=true}=s,c=chunkMQFZHA2D_js.c(s,["unstyled"]);return P__default.default.createElement(C,chunkMQFZHA2D_js.b(chunkMQFZHA2D_js.a({},c),{unstyled:l}))};return n.displayName=R,n}var u=e(chunkXIM7KMD6_js.a,"UnstyledConsentBanner"),y=e(chunkRLYTX3MM_js.a,"UnstyledConsentManager"),S=e(chunkZPKVLTSX_js.a,"UnstyledDSRRequestForm");exports.ConsentBanner=u;exports.ConsentManager=y;exports.DSRRequestForm=S;//# sourceMappingURL=unstyled.js.map
 //# sourceMappingURL=unstyled.js.map

package/dist/unstyled.mjs

@@ -1,3 +1,3 @@
 "use client";
-import {a as a$2}from'./chunk-EPT2K355.mjs';import {a as a$1}from'./chunk-BN77GP4W.mjs';import {a as a$3}from'./chunk-6HZL2WDU.mjs';import'./chunk-GKKAK6ES.mjs';import'./chunk-AYKLAEOU.mjs';import {c,b,a}from'./chunk-WWT2ZSNU.mjs';import P from'react';function e(C,R){let n=d=>{var s=d,{unstyled:l=true}=s,c$1=c(s,["unstyled"]);return P.createElement(C,b(a({},c$1),{unstyled:l}))};return n.displayName=R,n}var u=e(a$1,"UnstyledConsentBanner"),y=e(a$2,"UnstyledConsentManager"),S=e(a$3,"UnstyledDSRRequestForm");export{u as ConsentBanner,y as ConsentManager,S as DSRRequestForm};//# sourceMappingURL=unstyled.mjs.map
+import {a as a$2}from'./chunk-EPT2K355.mjs';import {a as a$1}from'./chunk-GN5C32JB.mjs';import {a as a$3}from'./chunk-6HZL2WDU.mjs';import'./chunk-GKKAK6ES.mjs';import'./chunk-AYKLAEOU.mjs';import {c,b,a}from'./chunk-WWT2ZSNU.mjs';import P from'react';function e(C,R){let n=d=>{var s=d,{unstyled:l=true}=s,c$1=c(s,["unstyled"]);return P.createElement(C,b(a({},c$1),{unstyled:l}))};return n.displayName=R,n}var u=e(a$1,"UnstyledConsentBanner"),y=e(a$2,"UnstyledConsentManager"),S=e(a$3,"UnstyledDSRRequestForm");export{u as ConsentBanner,y as ConsentManager,S as DSRRequestForm};//# sourceMappingURL=unstyled.mjs.map
 //# sourceMappingURL=unstyled.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tantainnovative/ndpr-toolkit",
-  "version": "3.4.1",
+  "version": "3.5.1",
   "private": false,
   "description": "Nigeria Data Protection Toolkit — enterprise-grade compliance components for the Nigeria Data Protection Act (NDPA) 2023",
   "keywords": [
@@ -231,6 +231,7 @@
   "devDependencies": {
     "@mdx-js/loader": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
+    "@microsoft/api-extractor": "^7.58.7",
     "@next/mdx": "^16.2.2",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-slot": "^1.2.4",
@@ -275,11 +276,10 @@
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.0.0"
   },
-  "dependencies": {},
   "scripts": {
     "dev": "next dev --turbopack",
     "build": "next build && node scripts/post-build.js",
-    "build:lib": "tsup && cp packages/ndpr-toolkit/src/styles.d.ts dist/styles.d.ts",
+    "build:lib": "tsup && cp packages/ndpr-toolkit/src/styles.d.ts dist/styles.d.ts && node scripts/rollup-dts.mjs",
     "start": "next start",
     "lint": "next lint .",
     "test": "jest --passWithNoTests",