@crownpeak/dqm-react-component 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Crownpeak DQM React Component - Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-10-30
+
+### Added
+- Initial release of @crownpeak/dqm-react-component
+- DQMSidebar component for quality analysis
+- ErrorBoundary component for error handling
+- Full TypeScript support with type definitions
+- Material-UI integration
+- Real-time quality analysis dashboard
+- Browser and source view for error highlighting
+- Category-based filtering
+- Accessibility compliance checking
+- Comprehensive documentation
+
+### Features
+- Quality scoring and checkpoint validation
+- WCAG 2.1 compliance checking
+- Visual error highlighting
+- Mobile responsive design
+- Export functionality for highlighted errors
+

package/DEVELOPMENT.md

@@ -0,0 +1,339 @@
+# Development Guide
+
+## Running the Complete Stack
+
+### Start Development (Frontend + Backend)
+
+```bash
+npm run dev
+```
+
+This runs both servers concurrently:
+- **Frontend (Vite)**: http://localhost:5173
+- **Backend (Express)**: http://localhost:3001
+
+### Start Individual Servers
+
+```bash
+# Frontend only
+npm run dev:client
+
+# Backend only
+npm run dev:server
+```
+
+## Project Structure
+
+```
+crownpeak-dqm-react-component/
+├── src/                          # React component source
+│   ├── components/
+│   │   ├── auth/                # Authentication components
+│   │   ├── sidebar/             # Sidebar UI components
+│   │   ├── cards/               # Analysis result cards
+│   │   ├── renderers/           # HTML rendering
+│   │   └── common/              # Shared components
+│   ├── utils/                   # Utilities
+│   ├── types.ts                 # TypeScript types
+│   ├── DQMSidebar.tsx          # Main component
+│   ├── index.ts                # Library entry point
+│   ├── App.tsx                 # Dev test harness
+│   └── main.tsx                # Dev app entry
+│
+├── server/                      # Backend API
+│   ├── routes/                 # API endpoints
+│   │   ├── auth.ts            # Authentication
+│   │   └── dqm.ts             # DQM proxy
+│   ├── services/              # Business logic
+│   │   ├── sessionStore.ts   # Session management
+│   │   └── dqmClient.ts      # DQM API client
+│   ├── middleware/            # Express middleware
+│   ├── config.ts              # Configuration
+│   ├── types.ts               # TypeScript types
+│   └── index.ts               # Express app
+│
+├── dist/                       # Build output
+│   ├── index.js               # Library ESM
+│   ├── index.cjs              # Library CommonJS
+│   ├── index.d.ts             # Type declarations
+│   └── server/                # Compiled server code
+│
+├── vite.config.ts             # Vite configuration
+├── tsconfig.json              # TypeScript base config
+├── tsconfig.lib.json          # Library build config
+├── tsconfig.server.json       # Server build config
+└── package.json               # Dependencies & scripts
+```
+
+## Authentication Modes
+
+The component supports two modes:
+
+### 1. Backend Mode (Recommended for Production)
+
+```tsx
+<DQMSidebar
+  config={{
+    authBackendUrl: 'http://localhost:3001',
+    useLocalStorage: true,
+  }}
+/>
+```
+
+- All API calls proxied through backend
+- Session token stored in localStorage
+- Real credentials never exposed to client
+
+### 2. Direct Mode (Development/Staging)
+
+```tsx
+<DQMSidebar
+  config={{
+    apiKey: 'YOUR_API_KEY',
+    websiteId: 'YOUR_WEBSITE_ID',
+  }}
+/>
+```
+
+- Direct communication with Crownpeak DQM API
+- Credentials in props or localStorage
+- No backend required
+
+## Testing Both Modes
+
+### Test Backend Mode
+
+1. Start both servers: `npm run dev`
+2. Open http://localhost:5173
+3. Click "Login" and enter credentials
+4. Backend validates and issues session token
+5. All API calls go through http://localhost:3001
+
+### Test Direct Mode
+
+1. Update `src/App.tsx`:
+```tsx
+<DQMSidebar
+  config={{
+    apiKey: 'YOUR_API_KEY',
+    websiteId: 'YOUR_WEBSITE_ID',
+  }}
+/>
+```
+
+2. Start frontend only: `npm run dev:client`
+3. No backend needed, direct API calls
+
+## Building for Production
+
+### Build Library
+
+```bash
+npm run build:lib
+```
+
+Output: `dist/index.{js,cjs,d.ts}`
+
+### Build Server
+
+```bash
+npm run build:server
+```
+
+Output: `dist/server/`
+
+### Test Library Build
+
+```bash
+npm pack
+# Creates: crownpeak-dqm-react-component-1.0.0.tgz
+```
+
+## Environment Configuration
+
+### Frontend (.env)
+
+```env
+VITE_BACKEND_URL=http://localhost:3001
+```
+
+### Backend (.env)
+
+```env
+PORT=3001
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+DQM_API_BASE_URL=https://api.crownpeak.net/dqm-cms/v1
+JWT_SECRET=your-secret-key
+```
+
+## API Testing with cURL
+
+### Login
+
+```bash
+curl -X POST http://localhost:3001/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "apiKey": "YOUR_API_KEY",
+    "websiteId": "YOUR_WEBSITE_ID"
+  }'
+```
+
+Response:
+```json
+{
+  "sessionToken": "abc123...",
+  "websiteId": "YOUR_WEBSITE_ID"
+}
+```
+
+### Start Analysis
+
+```bash
+curl -X POST http://localhost:3001/dqm/assets \
+  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "html": "<html><body><h1>Test</h1></body></html>",
+    "url": "https://example.com"
+  }'
+```
+
+### Get Results
+
+```bash
+curl -X GET http://localhost:3001/dqm/assets/ASSET_ID \
+  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
+```
+
+## Debugging
+
+### Enable Verbose Logging
+
+Backend logs all requests automatically. Check terminal output:
+
+```
+[2025-10-31T10:00:00.000Z] POST /auth/login
+[Auth] User logged in successfully (websiteId: test_id)
+[SessionStore] Created session: abc12345... (expires in 1440 minutes)
+```
+
+### Check Session Status
+
+```bash
+curl -X GET http://localhost:3001/auth/session \
+  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
+```
+
+### View Active Sessions (Dev Only)
+
+Add to `server/routes/auth.ts`:
+
+```typescript
+authRouter.get('/sessions/count', (req, res) => {
+  res.json({ count: sessionStore.count() });
+});
+```
+
+## Common Issues
+
+### CORS Errors
+
+**Problem:** Frontend can't reach backend
+
+**Solution:** Add frontend URL to `CORS_ORIGINS` in `.env`:
+```env
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+```
+
+### Port Already in Use
+
+**Problem:** `Error: listen EADDRINUSE: address already in use :::3001`
+
+**Solution:** Kill process or change port:
+```bash
+lsof -ti:3001 | xargs kill -9
+# or change PORT in .env
+```
+
+### Session Expired
+
+**Problem:** 401 Unauthorized after some time
+
+**Solution:** Session TTL is 24 hours. Login again or extend TTL in `server/config.ts`:
+```typescript
+session: {
+  ttl: 48 * 60 * 60 * 1000, // 48 hours
+}
+```
+
+### TypeScript Errors
+
+**Problem:** Type errors in server code
+
+**Solution:** Ensure @types packages installed:
+```bash
+npm install --save-dev @types/express @types/cors @types/node
+```
+
+## Production Deployment
+
+### Deploy Backend
+
+1. Build server: `npm run build:server`
+2. Copy `dist/server/` to production
+3. Set environment variables
+4. Install production dependencies only
+5. Start: `node dist/server/index.js`
+
+### Use Redis for Sessions
+
+Replace `server/services/sessionStore.ts` with Redis:
+
+```typescript
+import { createClient } from 'redis';
+
+const redis = createClient({
+  url: process.env.REDIS_URL
+});
+
+await redis.connect();
+
+export const sessionStore = {
+  create: async (apiKey, websiteId) => {
+    const token = generateToken();
+    await redis.setEx(`session:${token}`, 86400, JSON.stringify({
+      apiKey, websiteId, createdAt: Date.now()
+    }));
+    return token;
+  },
+  get: async (token) => {
+    const data = await redis.get(`session:${token}`);
+    return data ? JSON.parse(data) : null;
+  },
+  delete: async (token) => {
+    await redis.del(`session:${token}`);
+  }
+};
+```
+
+### Add Rate Limiting
+
+```bash
+npm install express-rate-limit
+```
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100 // limit each IP to 100 requests per windowMs
+});
+
+app.use('/auth/login', limiter);
+```
+
+## License
+
+MIT

package/EXAMPLES.md

@@ -0,0 +1,194 @@
+# Example Usage
+
+This directory contains example implementations of the `@crownpeak/dqm-react-component`.
+
+## Basic React App Example
+
+```tsx
+import React, {useState} from 'react';
+import {DQMSidebar} from '@crownpeak/dqm-react-component';
+
+function App() {
+    const [sidebarOpen, setSidebarOpen] = useState(false);
+
+    // Set DQM credentials (e.g., from environment variables)
+    React.useEffect(() => {
+        localStorage.setItem('dqm_apiKey', process.env.REACT_APP_DQM_API_KEY);
+        localStorage.setItem('dqm_websiteID', process.env.REACT_APP_DQM_WEBSITE_ID);
+    }, []);
+
+    return (
+        <div>
+            <h1>My Application with DQM</h1>
+            <p>This page is monitored by Crownpeak DQM for quality assurance.</p>
+
+            <DQMSidebar
+                open={sidebarOpen}
+                onClose={() => setSidebarOpen(false)}
+                onOpen={() => setSidebarOpen(true)}
+            />
+        </div>
+    );
+}
+
+export default App;
+```
+
+## Next.js Example
+
+```tsx
+// pages/_app.tsx
+import type {AppProps} from 'next/app';
+import {useEffect, useState} from 'react';
+import {DQMSidebar} from '@crownpeak/dqm-react-component';
+import {createTheme} from '@mui/material/styles';
+
+const theme = createTheme();
+
+function MyApp({Component, pageProps}: AppProps) {
+    const [sidebarOpen, setSidebarOpen] = useState(false);
+
+    useEffect(() => {
+        if (typeof window !== 'undefined') {
+            localStorage.setItem('dqm_apiKey', process.env.NEXT_PUBLIC_DQM_API_KEY!);
+            localStorage.setItem('dqm_websiteID', process.env.NEXT_PUBLIC_DQM_WEBSITE_ID!);
+        }
+    }, []);
+
+    return (
+        <>
+            <Component {...pageProps} />
+            <DQMSidebar
+                open={sidebarOpen}
+                onClose={() => setSidebarOpen(false)}
+                onOpen={() => setSidebarOpen(true)}
+            />
+        </>
+    );
+}
+
+export default MyApp;
+```
+
+## TypeScript Example with Custom Configuration
+
+```tsx
+import React, { useState, useCallback } from 'react';
+import { DQMSidebar, ErrorBoundary } from '@crownpeak/dqm-react-component';
+import type { DQMSidebarProps } from '@crownpeak/dqm-react-component';
+
+interface DQMConfig {
+  apiKey: string;
+  websiteId: string;
+  enabled: boolean;
+}
+
+const config: DQMConfig = {
+  apiKey: process.env.REACT_APP_DQM_API_KEY!,
+  websiteId: process.env.REACT_APP_DQM_WEBSITE_ID!,
+  enabled: process.env.NODE_ENV === 'production'
+};
+
+function App() {
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  React.useEffect(() => {
+    if (config.enabled) {
+      localStorage.setItem('dqm_apiKey', config.apiKey);
+      localStorage.setItem('dqm_websiteID', config.websiteId);
+    }
+  }, []);
+
+  const handleOpen = useCallback(() => {
+    setSidebarOpen(true);
+  }, []);
+
+  const handleClose = useCallback(() => {
+    setSidebarOpen(false);
+  }, []);
+
+  if (!config.enabled) {
+    return <div>DQM is disabled in this environment</div>;
+  }
+
+  return (
+    <ErrorBoundary>
+      <div>
+        <h1>App with DQM Quality Monitoring</h1>
+        <DQMSidebar
+          open={sidebarOpen}
+          onClose={handleClose}
+          onOpen={handleOpen}
+        />
+      </div>
+    </ErrorBoundary>
+  );
+}
+
+export default App;
+```
+
+## Conditional Rendering (Development Only)
+
+```tsx
+import React from 'react';
+import { DQMSidebar } from '@crownpeak/dqm-react-component';
+
+function App() {
+  const [sidebarOpen, setSidebarOpen] = React.useState(false);
+  const isDevelopment = process.env.NODE_ENV === 'development';
+
+  return (
+    <div>
+      <h1>My App</h1>
+      
+      {/* Only show DQM in development */}
+      {isDevelopment && (
+        <DQMSidebar
+          open={sidebarOpen}
+          onClose={() => setSidebarOpen(false)}
+          onOpen={() => setSidebarOpen(true)}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## With Custom Button Trigger
+
+```tsx
+import React, { useState } from 'react';
+import { DQMSidebar } from '@crownpeak/dqm-react-component';
+import { Button } from '@mui/material';
+import { Assessment } from '@mui/icons-material';
+
+function App() {
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  return (
+    <div>
+      <header>
+        <Button
+          variant="outlined"
+          startIcon={<Assessment />}
+          onClick={() => setSidebarOpen(true)}
+        >
+          Quality Check
+        </Button>
+      </header>
+
+      <main>
+        <h1>Content</h1>
+      </main>
+
+      <DQMSidebar
+        open={sidebarOpen}
+        onClose={() => setSidebarOpen(false)}
+        onOpen={() => setSidebarOpen(true)}
+      />
+    </div>
+  );
+}
+```
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Crownpeak Technology GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+