@crownpeak/dqm-react-component

v1.3.0

Published

2 days ago

A React component for Crownpeak Digital Quality Management (DQM) integration

0High
0Medium
0Low

react crownpeak dqm digital-quality-management accessibility quality-analysis mui component

Crownpeak DQM React Component

A React component library for integrating Crownpeak Digital Quality Management (DQM) into your React applications. Display quality analysis, accessibility violations, and checkpoint errors with visual highlighting capabilities.

🌟 Features

🤖 AI-Powered Translation & Summary - Automatically translate analysis results into your language and generate intelligent summaries using OpenAI
📊 Quality Analysis - Comprehensive quality metrics and scores
♿ Accessibility Checks - WCAG compliance validation
🎯 Error Highlighting - Visual highlighting of issues in HTML
🎨 Material-UI Design - Beautiful, responsive sidebar interface
🔐 Secure Authentication - Backend session management with secure credential storage
⚡ Real-time Analysis - Live quality assessment as you edit
📱 Responsive - Works on desktop, tablet, and mobile
🌍 Internationalization - Supports English, German, and Spanish
🔧 TypeScript Support - Full type definitions included

📦 Installation

npm install @crownpeak/dqm-react-component

🚀 Quick Start

import React, {useState} from 'react';
import {DQMSidebar} from '@crownpeak/dqm-react-component';

function App() {
    const [open, setOpen] = useState(false);

    const customHtml = `<html>
                <head><title>Test Page</title></head>
                <body>
                    <h1>Hello World</h1>
                    <img src="image.jpg" />
                </body>`

    return (
        <div>
            <button onClick={() => setOpen(true)}>Check Quality</button>

            <DQMSidebar
                open={sidebarOpen}
                onOpen={() => setOpen(true)}
                onClose={() => setOpen(false)}
                debugHtml={customHtml}
                config={{
                    // ... authentication options here
                    // look for "🔑 Authentication Setup" below
                }}
            />
        </div>
    );
}

export default App;

AI-Powered Translation & Summary (Quick Example)

import {DQMSidebar} from '@crownpeak/dqm-react-component';

<DQMSidebar
    open={isOpen}
    onClose={() => setIsOpen(false)}
    onOpen={() => setIsOpen(true)}
    config={{
        websiteId: 'your-website-id',
        apiKey: 'your-api-key',
        // Enable AI Translation (API key via localStorage: dqm_openai_apiKey)
        translation: {
            enabledByDefault: true,
            computeBudgetMs: 15000,   // 15s timeout for 'fast' mode
        },
        // Enable AI Summary (uses same OpenAI API key)
        summary: {
            timeoutMs: 30000,         // 30s timeout
        }
    }}
/>

See AI Features Guide for complete documentation including caching strategies and performance tuning.

📖 Documentation

Core Documentation

Quick Start Guide - Get up and running in 5 minutes
Examples - Integration examples for React, Next.js, TypeScript
Authentication Guide - Setup and configuration

AI Features

AI Features Guide - Translation & Summary with OpenAI
API Reference - Full TypeScript API documentation
Migration Guide - Upgrade from v1.1 to v1.2

Advanced

Widget Guide - Standalone IIFE/ESM bundle usage
Backend API - Backend server endpoints and usage
Development Guide - Contributing and local development
Troubleshooting - Common issues and solutions

🔑 Authentication Setup

The component requires authentication with Crownpeak DQM. Two options are available:

import {DQMSidebar} from '@crownpeak/dqm-react-component';

<DQMSidebar
    {/* ... */}
    config={{
        // Option 1: Direct API Key and Website ID (not recommended for production)
        // websiteId: 'your-website-id',
        // apiKey: 'your-api-key',

        // Option 2: Auth Backend for API Key management (recommended)
        authBackendUrl: '', // Dev: empty (same origin) | Prod: 'https://your-backend.com'
        useLocalStorage: true,
    }}

Direct Backend Integration

Run the included backend server for session management:

npm run server

See AUTHENTICATION.md for detailed setup instructions.

🛠️ Development Server

For local development with test harness:

npm install
npm run dev

This starts:

Frontend + Backend on http://localhost:5173 (Vite dev server with integrated backend)
Backend routes (/auth/*, /dqm/*) handled by Vite plugin

Standalone Server (Optional)

If using the included backend server:

Node.js 18+ or 20+
Redis (for session storage)

See REDIS-SETUP.md for Redis installation.

📊 API Reference

DQMSidebar Props

| Prop | Type | Required | Description | |-------------|--------------|----------|------------------------------| | open | boolean | ✅ | Controls sidebar visibility | | onClose | () => void | ✅ | Callback when sidebar closes | | onOpen | () => void | ✅ | Callback when sidebar opens | | debugHtml | string | ❌ | HTML for testing (dev only) | | config | DQMConfig | ❌ | Configuration options |

DQMConfig Options

| Option | Type | Default | Description | |-------------------|-----------------|---------|------------------------------------------------| | apiKey | string | - | Direct API key (not for production) | | websiteId | string | - | Website ID for DQM | | authBackendUrl | string | - | Backend URL for session management | | useLocalStorage | boolean | true | Persist credentials in localStorage | | disabled | boolean | false | Disable DQM completely | | disableLogout | boolean | false | Hide the logout control (host manages session) | | shadowDomMode | boolean | false | Enable for Shadow DOM embedding | | overlayConfig | OverlayConfig | - | Overlay/toolbar detection config |

OverlayConfig (for Toolbars & Overlays)

Configure how the sidebar adapts to fixed overlays (e.g., admin toolbars):

<DQMSidebar
    config={{
        overlayConfig: {
            // CSS selector for the overlay element
            selector: 'iframe#MyToolbar',

            // Validate iFrame has contentWindow (default: true)
            validateIframe: true,

            // Polling interval in ms for cross-origin iFrames (default: 1000)
            pollMs: 1000,

            // OR: Manual offset when auto-detection doesn't work
            // (e.g., for iFrames that fill screen but have smaller internal content)
            manualOffset: {
                position: 'top', // 'top' | 'bottom' | 'left' | 'right'
                pixels: 50
            }
        }
    }}
/>

Common overlay configurations:

// Disable overlay detection
overlayConfig: {
    selector: null
}

// Manual 50px offset from top
overlayConfig: {
    manualOffset: {
        position: 'top', pixels: 50
    }
}

// Custom selector without iFrame validation
overlayConfig: {
    selector: '.admin-toolbar', validateIframe: false
}

Exported Types

import type {
    AnalysisState,
    Checkpoint,
    AnalysisData,
    DQMSidebarProps,
    DQMConfig,
    OverlayConfig,
    OverlayOffsetPosition
} from '@crownpeak/dqm-react-component';

// For advanced overlay handling
import {useOverlayResistant} from '@crownpeak/dqm-react-component';
import type {OverlayInfo, OverlayPosition} from '@crownpeak/dqm-react-component';

See TypeScript examples for full type definitions.

🧪 Testing

# Lint code
npm run lint

# Build library
npm run build:lib

# Test as package
npm pack
npm install ./crownpeak-dqm-react-component-1.0.0.tgz

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📜 License

See LICENSE file for details.

🐛 Issues

Found a bug or have a feature request? Please open an issue.

📞 Support

Documentation: Check the docs folder
Issues: GitHub Issues
Website: crownpeak.com

🔗 Links

📝 Changelog

See CHANGELOG.md for release history.

Made with ❤️ by the Crownpeak team