@qualtrics/cocreate-guided-modal

cocreate-guided-modal

A React modal component for creating AI-powered projects with a guided experience. The modal includes a form with use case selection and project overview input, integrated with AI-powered project generation.

Installation

npm install @qualtrics/cocreate-guided-modal

Requirements

This package has the following peer dependencies:

• React ^18.0.0
• React DOM ^18.2.0
• @qualtrics/ui-react ^2.56.0
• react-hook-form ^7.54.2

Additional dependencies:

• @qualtrics/base-styles ^0.4.1
• @tanstack/react-query ^5.67.2
• axios ^1.8.2

Features

• Integrated with React Query for API calls
• Form validation using react-hook-form
• Responsive design with custom styling
• Built with @qualtrics/ui-react components
• Automatic redirection after successful submission

Usage

import { GuidedModal } from 'cocreate-guided-modal';
import type { ProjectInputs } from 'cocreate-guided-modal';

function App() {
  const [isOpen, setIsOpen] = React.useState(true);

  return (
    <GuidedModal
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
    />
  );
}

The component will automatically handle:

• Form state management
• API calls for project creation
• Redirection to the new project on success
• Error handling with fallback to catalog

Props

Prop	Type	Required	Description
isOpen	boolean	Yes	Controls the visibility of the modal
onClose	() => void	No	Callback function when modal is closed. If not provided, the close button will not be shown

Types

type ProjectInputs = {
  useCase: string;  // Currently defaults to "Voice of Customer"
  prompt: string;   // Free-form text for project details
};

Development

• Clone the repository
• Install dependencies:

npm install

• Available scripts:

npm run dev        # Start development server with Vite
npm run build     # Build the package using Rollup
npm run preview   # Preview the built package
npm run pack      # Create an npm package
npm run test-local # Build, pack and test the package locally

Testing Locally

To test the package locally:

• Build and pack the package:

npm run test-local

This will:

• Build the package
• Create a tarball
• Update the local testing environment
• Start the development server

Alternatively, you can manually link the package:

• Build the package:

npm run build

• Link the package globally:

npm link

• In your test project:

npm link @qualtrics/cocreate-guided-modal

• Import and use the component as shown in the Usage section above.

Building for Production

To build the package for production:

npm run build

This will generate the following outputs in the dist directory:

• CommonJS bundle (dist/index.js)
• ES Module bundle (dist/index.esm.js)
• UMD bundle (dist/index.umd.js)
• TypeScript declarations (dist/index.d.ts)

Styling

The component uses CSS modules for styling. The following classes are available:

• .modalBody - Custom styling for modal body
• .modalHorizontal - Horizontal layout container
• .modalContainer - Container for modal content
• .modalP - Paragraph styling
• .modalDivider - Divider line
• .modalVertical - Vertical layout container
• .modalFooter - Footer styling
• .modalButtons - Button container styling

Contributing

When contributing, please ensure:

• All new features include proper TypeScript types
• Maintain existing styling patterns
• Test thoroughly with the provided test project setup