JSPM – @citiwave/im-disclaimer-modal@1.1.0

Package Exports

@citiwave/im-disclaimer-modal

Readme

A customizable React component for displaying disclaimer/terms agreements with theme support. This component is designed to enhance user experience by providing clear and responsive terms agreements.

Installation

To install the package, use one of the following commands:

npm install @citiwave/im-disclaimer-modal
# or
yarn add @citiwave/im-disclaimer-modal

Quick Start

The easiest way to use the modal is with the DisclaimerProvider component. It will automatically show on first visit:

import { DisclaimerProvider } from '@citiwave/im-disclaimer-modal';
import '@citiwave/im-disclaimer-modal/dist/style.css';  // Don't forget the styles!

function App() {
  const disclaimerSections = [
    {
      title: 'Terms of Service',
      required: true,
      content: <div>Your terms content here...</div>
    }
  ];

  return (
    <DisclaimerProvider
      id="my-disclaimer"           // Unique ID for localStorage
      title="Agreement Required"   // Modal title
      disclaimerSections={disclaimerSections}
      theme="light"               // or "dark"
    />
  );
}

That's it! The modal will automatically:

Show on first visit
Save the user's choice in localStorage
Hide after acceptance
Not show again on future visits

Advanced Usage

For more control over the modal's behavior, you can use the lower-level components:

Using useDisclaimer Hook

import { DisclaimerModal, useDisclaimer } from '@citiwave/im-disclaimer-modal';
import '@citiwave/im-disclaimer-modal/dist/style.css';

const MyComponent = () => {
  const { isOpen, onClose, reset } = useDisclaimer('unique-id', {
    storagePrefix: 'my-app',
    defaultOpen: true
  });

  return (
    <DisclaimerModal
      isOpen={isOpen}
      onClose={onClose}
      title="Agreement Required"
      disclaimerSections={[...]}
      theme="light"
    />
  );
};

Requirements

To render the DisclaimerModal correctly, the following dependencies are required:

lucide-react version ^0.475.0 or higher.

If the required version of lucide-react is not available, the modal will automatically use fallback icons to ensure functionality.

Fallback Icons

In case the lucide-react library cannot be resolved, the modal will display default icons to maintain usability. This ensures that the modal remains functional even if the required icons are not available.

Features

Dark and Light theme support
Responsive design for all devices
TypeScript support
Customizable themes to match your application
Local storage persistence for user preferences
Smooth animations for a better user experience
Multi-section support for comprehensive agreements
JSON-based content structure
Content rendering utilities for dynamic content

Usage

The DisclaimerModal will automatically display on page load for first-time visitors. Once a user accepts the disclaimer, their choice is saved in localStorage and the modal won't show again unless explicitly reset.

Basic Usage with JSON Content

import { DisclaimerModal, useDisclaimer } from '@citiwave/im-disclaimer-modal';
import '@citiwave/im-disclaimer-modal/dist/style.css'; // Required: Import the styles

const MyComponent = () => {
  // The modal will automatically show on first visit
  const { isOpen, onClose } = useDisclaimer('unique-id', {
    storagePrefix: 'my-app',  // Optional: prefix for localStorage key
    defaultOpen: true         // Optional: controls initial state for new visitors (default: true)
  });

  // Your JSON content structure
  const disclaimerContent = {
    "terms": {
      "title": "Terms",
      "required": true,
      "content": {
        "title": "Important Information",
        "sections": [
          {
            "heading": "Forward-Looking Statements",
            "text": "Your disclaimer text here..."
          },
          {
            "heading": "Additional Terms",
            "text": "More terms...",
            "list": [
              "Item 1",
              "Item 2",
              "Item 3"
            ]
          }
        ]
      }
    }
  };

  // Transform the disclaimer sections
  const disclaimerSections = Object.entries(disclaimerContent).map(([key, section]) => ({
    title: section.title,
    required: section.required,
    content: renderDisclaimerContent(section.content, 'light') // or 'dark' for dark theme
  }));

  return (
    <DisclaimerModal
      isOpen={isOpen}
      onClose={onClose}
      title="Agreement Required"
      disclaimerSections={disclaimerSections}
      theme="light" // or "dark"
    />
  );
};

Simple Usage with Static Content

For simpler use cases, you can also use static content:

import { DisclaimerModal, useDisclaimer } from '@citiwave/im-disclaimer-modal';

const MyComponent = () => {
  const { isOpen, onClose } = useDisclaimer('unique-id', {
    storagePrefix: 'my-app',
    defaultOpen: true
  });

  const disclaimerSections = [
    {
      title: 'Terms of Service',
      required: true,
      content: <div>Your terms content here...</div>
    },
    {
      title: 'Privacy Policy',
      required: false,
      content: <div>Your privacy policy content here...</div>
    }
  ];

  return (
    <DisclaimerModal
      isOpen={isOpen}
      onClose={onClose}
      title="Agreement Required"
      disclaimerSections={disclaimerSections}
      theme="light" // or "dark"
    />
  );
};

The modal has three visibility states:

First Visit: Shows automatically (controlled by defaultOpen, defaults to true)
After Acceptance: Hidden (stored in localStorage)
Manual Control: Can be reset using the reset() function

const MyComponent = () => {
  const { isOpen, onClose, reset } = useDisclaimer('unique-id');

  // Use this to manually show the modal again
  const handleReset = () => {
    reset(); // Clears localStorage and shows the modal
  };

  return (
    <>
      <DisclaimerModal
        isOpen={isOpen}
        onClose={onClose}
        title="Agreement Required"
        disclaimerSections={[...]}
      />
      
      {/* Optional: Button to show the modal again */}
      <button onClick={handleReset}>Show Agreement</button>
    </>
  );
};

Common Mistakes

❌ Incorrect Usage: Using as a Constructor

// This is WRONG! Don't do this:
const modal = new DisclaimerModal({
  title: "Agreement Required",
  disclaimerSections: [...],
  theme: "light"
});

✅ Correct Usage: Using as a React Component

// This is the correct way:
import { DisclaimerModal, useDisclaimer } from '@citiwave/im-disclaimer-modal';
import '@citiwave/im-disclaimer-modal/dist/style.css'; // Don't forget to import the styles!

const MyComponent = () => {
  const { isOpen, onClose } = useDisclaimer('unique-id');
  
  return (
    <DisclaimerModal
      isOpen={isOpen}
      onClose={onClose}
      title="Agreement Required"
      disclaimerSections={[...]}
      theme="light"
    />
  );
};

Remember:

DisclaimerModal is a React component, use it with JSX syntax (<DisclaimerModal />)
Always import and use the useDisclaimer hook to manage the modal's state
Don't forget to import the CSS file

Props

Prop	Type	Default	Description
isOpen	boolean	false	Controls the visibility of the modal
onClose	function	-	Callback function when modal is closed
title	string	-	Modal title
disclaimerSections	array	[]	Array of sections to display
theme	string	'light'	Theme of the modal ('light' or 'dark')

useDisclaimer Hook Props

Prop	Type	Default	Description
id	string	-	Unique identifier for the disclaimer
options.storagePrefix	string	-	Prefix for local storage key
options.defaultOpen	boolean	true	Initial open state

License

MIT

@citiwave/im-disclaimer-modal