@crownpeak/dqm-react-component 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.1.0] - 2025-12-17
+
+### Added
+- **Overlay Configuration**: New `overlayConfig` option in `DQMConfig` for customizing overlay/toolbar detection
+  - `selector`: Custom CSS selector for overlay elements
+  - `validateIframe`: Option to validate iFrame contentWindow availability
+  - `pollMs`: Configurable polling interval for cross-origin iFrame detection
+  - `manualOffset`: Manual offset configuration for cases where auto-detection fails
+- **Enhanced `useDomPresence` Hook**: Now returns comprehensive element information including:
+  - `rect`: Element bounding rectangle (height, width, top, bottom, left, right)
+  - `position`: Detected position ('top', 'bottom', 'left', 'right', 'center')
+  - `contentOffset`: Ready-to-use offsets for positioning UI elements
+- **New Exports**: 
+  - `useOverlayResistant` hook for advanced overlay handling
+  - `OverlayConfig`, `OverlayOffsetPosition`, `OverlayInfo`, `OverlayPosition` types
+- **Standalone Widget Bundle**: New widget build (IIFE + ESM) with `initDQMWidget`, Shadow DOM isolation, and Emotion cache binding for safe embedding on any site.
+- **Widget Tooling & Types**: Added loader utilities, TypeScript declarations, and public exports for widget consumers.
+- **Integration Demos**: New demo pages for IIFE, ESM, dynamic loading, and standalone widget usage to test the bundled widget end-to-end.
+- **Config Option `disableLogout`**: Allows host apps to hide the sidebar logout control when session lifecycle is managed externally.
+
+### Changed
+- `useOverlayResistant` hook now accepts configuration options
+- `OverlayInfo` interface now includes `isManualOffset` flag
+- Sidebar header, content, footer, skeleton, and FAB now respect overlay offsets for consistent spacing around external toolbars.
+
+## [1.0.1] - 2025-12-08
+
+### Fixed
+- Resolved issue with error highlighting in certain browsers
+- Fixed TypeScript type definition for DQMSidebar props
+
 ## [1.0.0] - 2025-10-30
 
 ### Added

package/DEVELOPMENT.md

@@ -39,6 +39,7 @@ crownpeak-dqm-react-component/
 │   ├── index.ts                # Library entry point
 │   ├── App.tsx                 # Dev test harness
 │   └── main.tsx                # Dev app entry
+│   ├── html-pages/              # Widget entrypoint, loaders, declarations
 │
 ├── server/                      # Backend API
 │   ├── routes/                 # API endpoints
@@ -55,9 +56,14 @@ crownpeak-dqm-react-component/
 ├── dist/                       # Build output
 │   ├── index.js               # Library ESM
 │   ├── index.cjs              # Library CommonJS
-│   ├── index.d.ts             # Type declarations
+│   ├── index.d.ts             # Library type declarations
+│   ├── dqm-widget.esm.js      # Widget bundle (ESM)
+│   ├── dqm-widget.iife.js     # Widget bundle (IIFE)
+│   └── dqm-widget.d.ts        # Widget type declarations
 │   └── server/                # Compiled server code
 │
+├── test/                       # Demo pages for widget bundles
+├── public/                     # Landing page for demos
 ├── vite.config.ts             # Vite configuration
 ├── tsconfig.json              # TypeScript base config
 ├── tsconfig.lib.json          # Library build config
@@ -134,6 +140,14 @@ npm run build:lib
 
 Output: `dist/index.{js,cjs,d.ts}`
 
+### Build Widget Bundle
+
+```bash
+npm run build:widget
+```
+
+Output: `dist/dqm-widget.{esm.js,iife.js,d.ts}` (fully bundled, Shadow DOM-safe)
+
 ### Build Server
 
 ```bash
@@ -142,6 +156,14 @@ npm run build:server
 
 Output: `dist/server/`
 
+### Build Everything
+
+```bash
+npm run build
+```
+
+Runs library + widget + backend + auth UI builds.
+
 ### Test Library Build
 
 ```bash
@@ -149,6 +171,19 @@ npm pack
 # Creates: crownpeak-dqm-react-component-1.0.0.tgz
 ```
 
+### Preview Widget Bundle Locally
+
+```bash
+npm run build:widget
+npm run serve:widget
+```
+
+Serves `dist/` plus demo pages via `serve.json` rewrites:
+- `/test/demo-iife.html` for IIFE bundle
+- `/test/demo-esm.html` for ESM bundle
+- `/test/demo-dynamic.html` for lazy loading
+- `/test/widget-standalone.html` for full standalone demo
+
 ## Environment Configuration
 
 ### Frontend (.env)

package/EXAMPLES.md

@@ -192,3 +192,190 @@ function App() {
 }
 ```
 
+## 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

@@ -12,6 +12,13 @@ npm install
 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

package/README.md

@@ -70,6 +70,8 @@ export default App;
 - **[Authentication Guide](./AUTHENTICATION.md)** - OAuth 2.0 setup and configuration
 - **[Backend API](./BACKEND-API.md)** - API endpoints and usage
 - **[Development Guide](./DEVELOPMENT.md)** - Contributing and local development
+- **Standalone Widget** - Use the fully bundled widget via `/dist/dqm-widget.{esm.js,iife.js}` (see Quick Start and test
+  demos under `test/`)
 
 ## 🔑 Authentication Setup
 
@@ -143,6 +145,71 @@ See [REDIS-SETUP.md](./REDIS-SETUP.md) for Redis installation.
 | `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):
+
+```tsx
+<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:**
+
+[//]: # (@formatter:off)
+```tsx
+// 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
+}
+```
+[//]: # (@formatter:on)
 
 ### Exported Types
 
@@ -151,8 +218,15 @@ import type {
     AnalysisState,
     Checkpoint,
     AnalysisData,
-    DQMSidebarProps
+    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](./EXAMPLES.md#typescript-configuration) for full type definitions.

package/dist/DQMSidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DQMSidebar.d.ts","sourceRoot":"","sources":["../src/DQMSidebar.tsx"],"names":[],"mappings":"AACA,OAAO,KAAyC,MAAM,OAAO,CAAC;AAuC9D,OAAO,KAAK,EAA8B,eAAe,EAAc,MAAM,SAAS,CAAC;AAkBvF,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAonEhD,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"DQMSidebar.d.ts","sourceRoot":"","sources":["../src/DQMSidebar.tsx"],"names":[],"mappings":"AACA,OAAO,KAAyC,MAAM,OAAO,CAAC;AAuC9D,OAAO,KAAK,EAA8B,eAAe,EAAc,MAAM,SAAS,CAAC;AAoBvF,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAkpEhD,CAAC;AAEF,eAAe,UAAU,CAAC"}