kontenhumas-be/docs/FRONTEND_FORM_GENERATION_PROMPT.md

Frontend Form Generation Prompt

Overview

Generate comprehensive React/TypeScript forms for two main functionalities based on backend API specifications:

1. Approval Workflow Settings Form (API: /approval-workflows/with-client-settings)
2. User Levels Management Form (API: /user-levels)

---

1. APPROVAL WORKFLOW SETTINGS FORM

API Endpoint

POST /approval-workflows/with-client-settings

Request Structure

interface CreateApprovalWorkflowWithClientSettingsRequest {
  // Workflow details
  name: string;                    // required
  description: string;            // required
  isActive?: boolean;
  isDefault?: boolean;
  requiresApproval?: boolean;
  autoPublish?: boolean;
  steps: ApprovalWorkflowStepRequest[]; // required, min 1

  // Client approval settings
  clientApprovalSettings: ClientApprovalSettingsRequest;
}

interface ApprovalWorkflowStepRequest {
  stepOrder: number;               // required
  stepName: string;               // required
  requiredUserLevelId: number;   // required
  canSkip?: boolean;
  autoApproveAfterHours?: number;
  isActive?: boolean;

  // Multi-branch support fields
  parentStepId?: number;
  conditionType?: string;        // 'user_level', 'user_level_hierarchy', 'always', 'custom'
  conditionValue?: string;       // JSON string for conditions
  isParallel?: boolean;
  branchName?: string;
  branchOrder?: number;
}

interface ClientApprovalSettingsRequest {
  requiresApproval?: boolean;
  autoPublishArticles?: boolean;
  approvalExemptUsers: number[];
  approvalExemptRoles: number[];
  approvalExemptCategories: number[];
  requireApprovalFor: string[];
  skipApprovalFor: string[];
  isActive?: boolean;
}

CURL Request

curl -X 'POST' \
  'https://kontenhumas.com/api/approval-workflows/with-client-settings' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSU....' \
  -H 'Content-Type: application/json' \
  -d '{
  "autoPublish": true,
  "clientApprovalSettings": {
    "approvalExemptCategories": [],
    "approvalExemptRoles": [],
    "approvalExemptUsers": [],
    "autoPublishArticles": true,
    "isActive": true,
    "requireApprovalFor": [],
    "requiresApproval": true,
    "skipApprovalFor": []
  },
  "description": "Test",
  "isActive": true,
  "isDefault": true,
  "name": "Multi-Branch Jurnalis Approval",
  "requiresApproval": true,
  "steps": [
    {
      "stepOrder": 1,
      "stepName": "Single Approval",
      "requiredUserLevelId": 12,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [13]}",
      "branchName": "Single Approval"
    }
  ]
}'

Form Requirements

Section 1: Workflow Basic Information

• Workflow Name (Text Input, Required)

  • Label: "Workflow Name"
  • Placeholder: "e.g., Standard Article Approval"
  • Validation: Required, min 3 characters

• Description (Textarea, Required)

  • Label: "Workflow Description"
  • Placeholder: "Describe the purpose and process of this workflow"
  • Validation: Required, min 10 characters

• Workflow Settings (Checkbox Group)

  • ☐ Is Active (default: true)
  • ☐ Set as Default Workflow
  • ☐ Requires Approval (default: true)
  • ☐ Auto Publish After Approval (default: false)

Section 2: Workflow Steps (Dynamic Array)

• Add Step Button - Allow adding multiple steps

• Step Configuration (for each step):

  • Step Order (Number Input, Required)

    • Label: "Step Order"
    • Default: Auto-increment (1, 2, 3...)
    • Validation: Required, unique within workflow

  • Step Name (Text Input, Required)

    • Label: "Step Name"
    • Placeholder: "e.g., Editor Review, Manager Approval"
    • Validation: Required, min 3 characters

  • Required User Level (Select Dropdown, Required)

    • Label: "Required User Level"
    • Options: Fetch from /user-levels API
    • Display: {name} (Level {levelNumber})
    • Validation: Required

  • Step Settings (Checkbox Group)

    • ☐ Can Skip This Step
    • ☐ Is Active (default: true)

  • Auto Approval (Number Input, Optional)

    • Label: "Auto Approve After Hours"
    • Placeholder: "Leave empty for manual approval"
    • Help Text: "Automatically approve after specified hours"

  • Advanced Settings (Collapsible Section)

    • Parent Step (Select Dropdown, Optional)

      • Label: "Parent Step (for branching)"
      • Options: Previous steps in workflow
      • Help Text: "Select parent step for parallel branches"

    • Condition Type (Select Dropdown, Optional)

      • Label: "Condition Type"
      • Options: ['always', 'user_level', 'user_level_hierarchy', 'custom']
      • Default: 'always'

    • Condition Value (Text Input, Optional)

      • Label: "Condition Value (JSON)"
      • Placeholder: '{"minLevel": 3}'
      • Help Text: "JSON string for custom conditions"

    • Branch Settings (Checkbox Group)

      • ☐ Is Parallel Step
      • Branch Name (Text Input, Optional)
        • Label: "Branch Name"
        • Placeholder: "e.g., technical, content"
      • Branch Order (Number Input, Optional)
        • Label: "Branch Order"

• Step Actions

  • Move Up/Down buttons
  • Delete Step button
  • Duplicate Step button

Section 3: Client Approval Settings

• Global Approval Settings (Checkbox Group)

  • ☐ Requires Approval (default: true)
  • ☐ Auto Publish Articles (default: false)
  • ☐ Is Active (default: true)

• Exemptions (Multi-select sections)

  • Exempt Users (Multi-select)

    • Label: "Users Exempt from Approval"
    • Options: Fetch from /users API
    • Display: {fullname} ({username})
    • Searchable: Yes

  • Exempt Roles (Multi-select)

    • Label: "Roles Exempt from Approval"
    • Options: Fetch from /user-roles API
    • Display: {roleName}
    • Searchable: Yes

  • Exempt Categories (Multi-select)

    • Label: "Categories Exempt from Approval"
    • Options: Fetch from /article-categories API
    • Display: {categoryName}
    • Searchable: Yes

• Content Type Rules (Dynamic Arrays)

  • Require Approval For (Tag Input)

    • Label: "Content Types Requiring Approval"
    • Placeholder: "e.g., news, article, blog"
    • Help Text: "Press Enter to add content type"

  • Skip Approval For (Tag Input)

    • Label: "Content Types Skipping Approval"
    • Placeholder: "e.g., announcement, update"
    • Help Text: "Press Enter to add content type"

Form Features

• Real-time Validation
• Step-by-step Wizard (Optional)
• Preview Mode - Show workflow visualization
• Save as Draft functionality
• Form Reset with confirmation
• Auto-save every 30 seconds

---

2. USER LEVELS MANAGEMENT FORM

API Endpoint

POST /user-levels

Request Structure

interface UserLevelsCreateRequest {
  name: string;                    // required
  aliasName: string;              // required
  levelNumber: number;            // required
  parentLevelId?: number;
  provinceId?: number;
  group?: string;
  isApprovalActive?: boolean;
  isActive?: boolean;
}

Form Requirements

Section 1: Basic Information

• Level Name (Text Input, Required)

  • Label: "Level Name"
  • Placeholder: "e.g., Senior Editor, Manager, Publisher"
  • Validation: Required, min 3 characters, unique

• Alias Name (Text Input, Required)

  • Label: "Alias Name"
  • Placeholder: "e.g., SENIOR_EDITOR, MANAGER, PUBLISHER"
  • Validation: Required, uppercase, unique
  • Help Text: "Short identifier for system use"

• Level Number (Number Input, Required)

  • Label: "Level Number"
  • Placeholder: "e.g., 1, 2, 3"
  • Validation: Required, unique, positive integer
  • Help Text: "Higher number = higher authority"

Section 2: Hierarchy Settings

• Parent Level (Select Dropdown, Optional)

  • Label: "Parent Level"
  • Options: Fetch from /user-levels API
  • Display: {name} (Level {levelNumber})
  • Help Text: "Select parent level for hierarchy"

• Province (Select Dropdown, Optional)

  • Label: "Province"
  • Options: Fetch from /provinces API
  • Display: {provinceName}
  • Help Text: "Geographic scope for this level"

• Group (Text Input, Optional)

  • Label: "Group"
  • Placeholder: "e.g., Editorial, Management, Technical"
  • Help Text: "Group classification for organization"

Section 3: Approval Settings

• Approval Settings (Checkbox Group)
  • ☐ Is Approval Active (default: true)
    • Help Text: "Users with this level can participate in approval process"
  • ☐ Is Active (default: true)
    • Help Text: "Level is available for assignment"

Form Features

• Level Number Validation - Prevent duplicate level numbers
• Hierarchy Visualization - Show level hierarchy tree
• Bulk Operations - Create multiple levels at once
• Import/Export - CSV import/export functionality
• Level Preview - Show how level fits in hierarchy

---

3. COMMON FORM COMPONENTS

Form Layout

• Responsive Design - Mobile-first approach
• Multi-step Wizard - For complex forms
• Tabbed Interface - For different sections
• Collapsible Sections - For advanced settings

Validation

• Real-time Validation - Show errors as user types
• Cross-field Validation - Validate relationships between fields
• Server-side Validation - Handle API validation errors
• Custom Validation Rules - Business logic validation

User Experience

• Auto-complete - For select fields
• Search Functionality - For large option lists
• Drag & Drop - For reordering steps/items
• Keyboard Navigation - Full keyboard support
• Accessibility - ARIA labels, screen reader support

Data Management

• Form State Management - Redux/Zustand
• Local Storage - Save draft forms
• API Integration - Axios/Fetch with error handling
• Loading States - Spinners, skeleton screens
• Success/Error Messages - Toast notifications

Styling Requirements

• Design System - Consistent with existing app
• Dark/Light Mode - Theme support
• Custom Components - Reusable form components
• Animation - Smooth transitions
• Icons - Meaningful icons for actions

---

4. IMPLEMENTATION NOTES

API Integration

// Example API calls
const createWorkflow = async (data: CreateApprovalWorkflowWithClientSettingsRequest) => {
  const response = await fetch('/api/approval-workflows/with-client-settings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(data)
  });
  return response.json();
};

const createUserLevel = async (data: UserLevelsCreateRequest) => {
  const response = await fetch('/api/user-levels', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(data)
  });
  return response.json();
};

Form Libraries

• React Hook Form - For form management
• Yup/Zod - For validation
• React Select - For advanced select components
• React DnD - For drag and drop
• React Query - For API state management

Component Structure

components/
├── forms/
│   ├── ApprovalWorkflowForm/
│   │   ├── index.tsx
│   │   ├── WorkflowBasicInfo.tsx
│   │   ├── WorkflowSteps.tsx
│   │   ├── ClientSettings.tsx
│   │   └── StepForm.tsx
│   └── UserLevelsForm/
│       ├── index.tsx
│       ├── BasicInfo.tsx
│       ├── HierarchySettings.tsx
│       └── ApprovalSettings.tsx
├── common/
│   ├── FormField.tsx
│   ├── DynamicArray.tsx
│   ├── MultiSelect.tsx
│   └── ValidationMessage.tsx

State Management

// Form state structure
interface FormState {
  workflowForm: {
    data: CreateApprovalWorkflowWithClientSettingsRequest;
    errors: Record<string, string>;
    isValid: boolean;
    isSubmitting: boolean;
  };
  userLevelsForm: {
    data: UserLevelsCreateRequest;
    errors: Record<string, string>;
    isValid: boolean;
    isSubmitting: boolean;
  };
}

This prompt provides comprehensive specifications for generating both forms with all necessary fields, validation rules, user experience considerations, and implementation details based on the backend API structures.