@crownpeak/dqm-react-component 1.1.0 → 1.2.1

package/EXAMPLES.md

@@ -1,381 +0,0 @@
-# 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>
-  );
-}
-```
-
-## With Overlay/Toolbar Configuration
-
-Use `overlayConfig` to offset the sidebar when toolbars or overlays are present.
-
-### Auto-Detection (Toolbar Selector)
-
-```tsx
-import { DQMSidebar } from '@crownpeak/dqm-react-component';
-
-function App() {
-  const [sidebarOpen, setSidebarOpen] = useState(false);
-
-  return (
-    <DQMSidebar
-      open={sidebarOpen}
-      onClose={() => setSidebarOpen(false)}
-      onOpen={() => setSidebarOpen(true)}
-      config={{
-        overlayConfig: {
-          // Example toolbar anchored to the top edge
-          selector: '.preview-toolbar',
-          validateIframe: false
-        }
-      }}
-    />
-  );
-}
-```
-### Auto-Detection (Custom Selector)
-
-```tsx
-import { DQMSidebar } from '@crownpeak/dqm-react-component';
-
-function App() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <DQMSidebar
-      open={open}
-      onClose={() => setOpen(false)}
-      onOpen={() => setOpen(true)}
-      config={{
-        overlayConfig: {
-          selector: 'iframe#my-overlay',
-        }
-      }}
-    />
-  );
-}
-```
-
-### Custom Selector
-
-```tsx
-import { DQMSidebar } from '@crownpeak/dqm-react-component';
-
-function App() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <DQMSidebar
-      open={open}
-      onClose={() => setOpen(false)}
-      onOpen={() => setOpen(true)}
-      config={{
-        overlayConfig: {
-          // Custom selector for your admin toolbar
-          selector: '.admin-toolbar-header',
-          // Disable iFrame validation for non-iFrame elements
-          validateIframe: false,
-        }
-      }}
-    />
-  );
-}
-```
-
-### Manual Offset (for Cross-Origin iFrames)
-
-When the overlay is a cross-origin iFrame that fills the entire screen but has
-a smaller internal toolbar, auto-detection won't work. Use manual offset:
-
-```tsx
-import { DQMSidebar } from '@crownpeak/dqm-react-component';
-
-function App() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <DQMSidebar
-      open={open}
-      onClose={() => setOpen(false)}
-      onOpen={() => setOpen(true)}
-      config={{
-        overlayConfig: {
-          // Manual offset: 50px from the top
-          manualOffset: {
-            position: 'top',
-            pixels: 50
-          }
-        }
-      }}
-    />
-  );
-}
-```
-
-### Disable Overlay Detection
-
-```tsx
-import { DQMSidebar } from '@crownpeak/dqm-react-component';
-
-function App() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <DQMSidebar
-      open={open}
-      onClose={() => setOpen(false)}
-      onOpen={() => setOpen(true)}
-      config={{
-        overlayConfig: {
-          // Disable all overlay detection
-          selector: null
-        }
-      }}
-    />
-  );
-}
-```
-
-### Disable Logout Button
-
-```tsx
-import { DQMSidebar } from '@crownpeak/dqm-react-component';
-
-function App() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <DQMSidebar
-      open={open}
-      onClose={() => setOpen(false)}
-      onOpen={() => setOpen(true)}
-      config={{
-        // Host app controls session lifecycle; hide logout control in the sidebar
-        disableLogout: true,
-      }}
-    />
-  );
-}
-```
-
-### Advanced: Using the Hook Directly
-
-For custom UI components that need overlay information:
-
-```tsx
-import { useOverlayResistant } from '@crownpeak/dqm-react-component';
-import type { OverlayInfo } from '@crownpeak/dqm-react-component';
-
-function MyFloatingButton() {
-  const overlay: OverlayInfo = useOverlayResistant({
-    selector: '...',
-    validateIframe: true,
-    pollMs: 1000,
-  });
-
-  return (
-    <button
-      style={{
-        position: 'fixed',
-        top: overlay.present 
-          ? `${overlay.contentOffset.top + 16}px` 
-          : '16px',
-        right: '16px',
-        zIndex: 9999,
-      }}
-    >
-      {overlay.present 
-        ? `Toolbar at ${overlay.position} (${overlay.height}px)` 
-        : 'No toolbar detected'}
-    </button>
-  );
-}
-```
-

package/QUICKSTART.md

@@ -1,207 +0,0 @@
-# 🚀 Quick Start Guide
-
-## Installation
-
-```bash
-npm install
-```
-
-## Build
-
-```bash
-npm run build
-```
-
-### Build widget only (for standalone script usage)
-
-```bash
-npm run build:widget
-npm run serve:widget   # preview demos at http://localhost:4173/test/demo-iife.html etc.
-```
-
-## Start Development
-
-```bash
-npm run dev
-```
-
-This starts:
-- ✅ **Frontend**: http://localhost:5173 (Vite Dev Server)
-- ✅ **Backend**: http://localhost:3001 (Express API)
-
-## Test the Integration
-
-### 1. Open Frontend
-Navigate to http://localhost:5173
-
-### 2. Configure Backend Mode
-The test harness is already configured to use the backend:
-
-```tsx
-config={{
-  authBackendUrl: 'http://localhost:3001',
-  useLocalStorage: true,
-}}
-```
-
-### 3. Login with Credentials
-- Enter your Crownpeak DQM API Key
-- Enter your Website ID
-- Click "Continue"
-
-The backend will:
-1. Validate credentials with Crownpeak DQM API
-2. Issue a session token
-3. Store token in localStorage
-
-### 4. Analyze HTML
-- Paste HTML in the editor
-- Click "Start Analysis"
-- All requests go through `http://localhost:3001/dqm/*`
-
-## Architecture
-
-```mermaid
-graph LR
-A[React App<br/>Port 5173]
-B[Express API<br/>Port 3001]
-C[Crownpeak DQM<br/>API]
-
-    A -->|HTTP Requests| B
-    B -->|Proxied Requests| C
-    
-    A -.->|sessionToken<br/>localStorage| A
-    B -.->|apiKey + websiteId<br/>in-memory · Redis-ready| B
-    
-    subgraph Frontend
-        A
-        A1[DQMSidebar]
-        A2[Login UI]
-        A3[HTML Editor]
-    end
-    
-    subgraph Backend
-        B
-        B1[Auth Routes]
-        B2[DQM Proxy]
-        B3[Sessions]
-    end
-    
-    subgraph External
-        C
-        C1[Analysis]
-        C2[Highlights]
-        C3[Checkpoints]
-    end
-```
-
-## Two Authentication Modes
-
-### Backend Mode (Production)
-```tsx
-config={{
-  authBackendUrl: 'http://localhost:3001',
-}}
-```
-- ✅ Secure session tokens
-- ✅ API keys never exposed to client
-- ✅ Centralized access control
-
-### Direct Mode (Development)
-```tsx
-config={{
-  apiKey: 'YOUR_API_KEY',
-  websiteId: 'YOUR_WEBSITE_ID',
-}}
-```
-- ✅ No backend required
-- ✅ Quick testing
-- ✅ Props or localStorage
-
-## API Endpoints
-
-### Authentication
-- `POST /auth/login` - Login with credentials
-- `POST /auth/logout` - Invalidate session
-- `GET /auth/session` - Get session info
-
-### DQM Proxy
-- `POST /dqm/assets` - Start analysis
-- `GET /dqm/assets/:id` - Get results
-- `GET /dqm/assets/:id/pagehighlight/all` - All highlights
-- `GET /dqm/assets/:id/pagehighlight/:cpId` - Single highlight
-
-All DQM endpoints require `Authorization: Bearer <sessionToken>`
-
-## Scripts
-
-```bash
-# Development
-npm run dev              # Start both servers
-npm run dev:client       # Frontend only
-npm run dev:server       # Backend only
-
-# Build
-npm run build            # Build all
-npm run build:lib        # Build React library
-npm run build:server     # Build Express server
-
-# Production
-npm run start:server     # Run built server
-```
-
-## Environment Setup
-
-Copy `.env.example` to `.env`:
-
-```env
-PORT=3001
-CORS_ORIGINS=http://localhost:5173
-DQM_API_BASE_URL=https://api.crownpeak.net/dqm-cms/v1
-JWT_SECRET=your-secret-key
-```
-
-## Documentation
-
-- **[BACKEND-API.md](./BACKEND-API.md)** - Backend API specification
-- **[DEVELOPMENT.md](./DEVELOPMENT.md)** - Development guide
-- **[server/README.md](./server/README.md)** - Server documentation
-- **[AUTHENTICATION.md](./AUTHENTICATION.md)** - Auth flow details
-- **[EXAMPLES.md](./EXAMPLES.md)** - Integration examples
-
-## Testing
-
-### Test Backend Health
-```bash
-curl http://localhost:3001/health
-```
-
-### Test Login
-```bash
-curl -X POST http://localhost:3001/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"apiKey":"YOUR_KEY","websiteId":"YOUR_ID"}'
-```
-
-### Test Analysis
-```bash
-curl -X POST http://localhost:3001/dqm/assets \
-  -H "Authorization: Bearer YOUR_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"html":"<html><body>Test</body></html>"}'
-```
-
-## Features
-
-✅ **Modular Backend** - Express.js with clean architecture  
-✅ **Session Management** - In-memory store (Redis-ready)  
-✅ **DQM API Proxy** - All analysis endpoints  
-✅ **CORS & Security** - Helmet.js, CORS whitelist  
-✅ **Auto-reload** - TSX watch mode for development  
-✅ **Concurrent Servers** - Frontend + Backend in one command  
-✅ **TypeScript** - Full type safety  
-✅ **Error Handling** - Centralized middleware  
-
-## License
-
-MIT