@mbc-cqrs-serverless/survey-web

A comprehensive React component library for building dynamic surveys and forms, built for Next.js applications.

Features

• 🎨 Modern UI Components - Built with Radix UI and Tailwind CSS
• 📝 Dynamic Survey Builder - Create surveys with drag-and-drop interface
• 🔧 Multiple Question Types - Short text, long text, single/multiple choice, linear scale, rating, date, time
• ✅ Advanced Validation - Custom validation rules with Zod schema validation
• 🔄 Real-time Updates - AWS AppSync integration for live data synchronization
• 📱 Responsive Design - Mobile-first approach with responsive layouts
• 🎯 TypeScript Support - Full TypeScript support with comprehensive type definitions

Installation

npm install @mbc-cqrs-serverless/survey-web

Environment Variables Setup

Required Environment Variables

Create a .env.local file in your Next.js project root with the following variables:

# AWS AppSync Configuration
NEXT_PUBLIC_AWS_APPSYNC_GRAPHQLENDPOINT=https://your-appsync-endpoint.amazonaws.com/graphql
NEXT_PUBLIC_AWS_APPSYNC_APIKEY=your-appsync-api-key
NEXT_PUBLIC_AWS_APPSYNC_REGION=us-east-1

# API Configuration
NEXT_PUBLIC_API_URL=https://your-api-endpoint.com
NEXT_PUBLIC_TENANT_CODE=your-tenant-code

# AWS Amplify Configuration (if using Cognito authentication)
NEXT_PUBLIC_AWS_REGION=us-east-1
NEXT_PUBLIC_AWS_USER_POOL_ID=your-user-pool-id
NEXT_PUBLIC_AWS_USER_POOL_WEB_CLIENT_ID=your-client-id

Environment Variables Explained

| Variable | Description | Required | | ----------------------------------------- | ----------------------------------------------- | -------- | | NEXT_PUBLIC_AWS_APPSYNC_GRAPHQLENDPOINT | Your AWS AppSync GraphQL endpoint URL | ✅ | | NEXT_PUBLIC_AWS_APPSYNC_APIKEY | Your AWS AppSync API key for authentication | ✅ | | NEXT_PUBLIC_AWS_APPSYNC_REGION | AWS region where your AppSync API is deployed | ✅ | | NEXT_PUBLIC_API_URL | Base URL for your REST API endpoints | ✅ | | NEXT_PUBLIC_TENANT_CODE | Tenant identifier for multi-tenant applications | ✅ | | NEXT_PUBLIC_AWS_REGION | AWS region for Amplify configuration | Optional | | NEXT_PUBLIC_AWS_USER_POOL_ID | Cognito User Pool ID for authentication | Optional | | NEXT_PUBLIC_AWS_USER_POOL_WEB_CLIENT_ID | Cognito User Pool Web Client ID | Optional |

Usage

1. Basic Setup

First, import the CSS styles in your Next.js application:

// pages/_app.tsx or app/layout.tsx
import '@mbc-cqrs-serverless/survey-web/styles.css'

2. Survey Template Management

import { SurveyTemplatePage } from '@mbc-cqrs-serverless/survey-web/SurveyTemplatePage'

export default function SurveyTemplates() {
  return <SurveyTemplatePage />
}

3. Edit Survey Template

import { EditSurveyTemplatePage } from '@mbc-cqrs-serverless/survey-web/EditSurveyTemplatePage'

export default function EditSurvey({ params }: { params: { id: string } }) {
  return <EditSurveyTemplatePage id={params.id} />
}

4. Survey Form (Public-facing)

import { SurveyForm } from '@mbc-cqrs-serverless/survey-web/SurveyForm'

export default function Survey({ schema }: { schema: SurveySchemaType }) {
  return (
    <SurveyForm
      schema={schema}
      onSubmit={(answers, meta) => saveAnswer(answers, meta)}
    />
  )
}

answers is keyed by question id; meta lists each question's id, label, type and value.

To edit a saved answer, pass it as defaultValues. It is read once on mount, so render the form after the answer has loaded (or remount it with key). Answers to questions that were removed from the schema since are dropped on submit.

<SurveyForm
  key={answer.id}
  schema={schema}
  defaultValues={answer.answers}
  submitLabel="回答を更新"
  onSubmit={(answers, meta) => updateAnswer(answer.id, answers, meta)}
/>

Question Types

The library supports various question types:

Text Questions

• Short Text - Single line text input with validation
• Long Text - Multi-line text input (paragraph)

Choice Questions

• Single Choice - Radio buttons with conditional logic
• Multiple Choice - Checkboxes with min/max selection
• Dropdown - Select dropdown with options

Scale Questions

• Linear Scale - Numeric scale with custom min/max
• Rating - Star/heart/thumb rating system

Date/Time Questions

• Date - Date picker with optional time
• Time - Time picker for time or duration

Locked Questions

Set locked: true on a question to make it fixed in the survey creator: it cannot be edited, deleted, duplicated or dragged, and a section containing it cannot be deleted. Duplicating such a section produces unlocked copies. The lock is enforced in the UI only — validate it on the server if it must not be bypassed.

{ id: 'q_email', type: 'short-text', label: 'Email', locked: true }

Locked Sections

Set locked: true on a section header to fix the section in the survey creator: its title and description cannot be edited, it cannot be deleted or merged (nor can the section below merge into it), and nothing can be added into it. The floating action bar is hidden while the section or one of its questions is selected, and questions cannot be dragged in or out. The section can still be moved, and duplicating it produces an unlocked copy. Questions inside keep their own locked flag.

{ id: 'sec_profile', type: 'section-header', title: 'Profile', locked: true }

Validation Rules

Text Validation

{
  validation: {
    required: true,
    custom: {
      type: "length",
      rule: "min",
      value: 5,
      customError: "Minimum 5 characters required"
    }
  }
}

Number Validation

{
  validation: {
    custom: {
      type: "number",
      rule: "between",
      value: 18,
      value2: 65,
      customError: "Age must be between 18 and 65"
    }
  }
}

Email Validation

{
  validation: {
    custom: {
      type: "text",
      rule: "is_email",
      customError: "Please enter a valid email address"
    }
  }
}

API Integration

The library automatically handles:

• Authentication - AWS Amplify session tokens
• GraphQL Queries - AppSync integration for real-time data
• REST API Calls - Axios-based HTTP client with interceptors
• Error Handling - Comprehensive error management

Development

Building the Package

npm run build

Development Mode

npm run dev

Type Checking

npm run type-check

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install next@^14.0.0 react@^18.0.0 react-dom@^18.0.0

Documentation

For detailed documentation, guides, and API reference, visit the official documentation site:

• Survey Web Documentation

License

MIT © Murakami Business Consulting, Inc.

Support

For issues and questions, please visit our GitHub repository.