@crownpeak/dqm-react-component-dev-mcp 1.2.0

package/data/DOCS-STRUCTURE.md

@@ -0,0 +1,307 @@
+# Documentation Structure
+
+This document explains how documentation is organized and maintained in this repository.
+
+## Single Source of Truth
+
+**All documentation lives in `/docs`** - no duplicates elsewhere.
+
+## Directory Structure
+
+```
+/
+├── docs/                       📚 SINGLE SOURCE OF TRUTH
+│   ├── QUICKSTART.md          - Quick start guide
+│   ├── EXAMPLES.md            - Integration examples (10 examples)
+│   ├── AUTHENTICATION.md      - Auth configuration + 3 Mermaid diagrams
+│   ├── AI-FEATURES.md         - AI features + 4 Mermaid diagrams
+│   ├── WIDGET-GUIDE.md        - Widget bundles + 1 Mermaid diagram
+│   ├── MIGRATION-GUIDE.md     - v1.0→v1.1 migration
+│   ├── API-REFERENCE.md       - TypeScript API (800+ lines)
+│   ├── TROUBLESHOOTING.md     - FAQ + error codes (600+ lines)
+│   ├── BACKEND-API.md         - Backend server docs
+│   ├── DEVELOPMENT.md         - Development guide
+│   ├── NPM-PUBLISH.md         - npm publishing workflow
+│   ├── REDIS-SETUP.md         - Redis configuration
+│   └── SERVER.md              - Server documentation
+│
+├── wiki/                       🔨 BUILD OUTPUT (gitignored except templates)
+│   ├── Home.md                - Wiki home page (template, committed)
+│   ├── _Sidebar.md            - Navigation (template, committed)
+│   ├── README.md              - Wiki docs (committed)
+│   └── *.md                   - Generated from docs/ (NOT committed)
+│
+└── Root (GitHub features only)
+    ├── README.md              - Repository landing page
+    ├── CHANGELOG.md           - Release notes
+    ├── CONTRIBUTING.md        - Contribution guidelines (GitHub feature)
+    ├── CODE_OF_CONDUCT.md     - Code of conduct (GitHub feature)
+    └── LICENSE                - MIT license
+```
+
+## Why This Structure?
+
+### `/docs` as Single Source
+
+✅ **No Duplication** - Documentation exists in ONE place only  
+✅ **Version Control** - Docs are versioned with code in Git  
+✅ **Pull Request Reviews** - Documentation changes reviewed with code  
+✅ **Developer Access** - Developers have docs locally when they clone  
+✅ **Branch Support** - Different docs for different branches  
+
+### `wiki/` as Build Output
+
+✅ **Automated Generation** - Built from `/docs` via `scripts/wiki-build.sh`  
+✅ **Clean Git History** - Generated files not committed (in `.gitignore`)  
+✅ **Deploy Target** - `scripts/wiki-deploy.sh` pushes to GitHub Wiki  
+✅ **Link Conversion** - Links automatically converted to Wiki format  
+
+### Root Stays Minimal
+
+✅ **GitHub Features** - `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` used by GitHub  
+✅ **Landing Page** - `README.md` shown on repository homepage  
+✅ **Visibility** - Important files remain at root for easy discovery  
+
+## Workflow
+
+### Editing Documentation
+
+1. **Edit source files in `/docs`:**
+   ```bash
+   vim docs/QUICKSTART.md
+   vim docs/AI-FEATURES.md
+   ```
+
+2. **Commit to repository:**
+   ```bash
+   git add docs/
+   git commit -m "docs: update quick start guide"
+   git push origin feat/localization
+   ```
+
+### Deploying to GitHub Wiki
+
+1. **Build wiki from docs:**
+   ```bash
+   ./scripts/wiki-build.sh
+   ```
+   This creates `wiki/*.md` files with converted links.
+
+2. **Deploy to GitHub Wiki:**
+   ```bash
+   ./scripts/wiki-deploy.sh "Update AI features documentation"
+   ```
+   This pushes `wiki/` to the GitHub Wiki repository.
+
+### One-Step Deployment
+
+```bash
+# Build and deploy in one command
+./scripts/wiki-deploy.sh "Update documentation"
+```
+
+The deploy script automatically runs `wiki-build.sh` first.
+
+## Link Formats
+
+### In `/docs` (Repository)
+
+Use standard markdown links:
+
+```markdown
+[Quick Start](./QUICKSTART.md)
+[Examples](./EXAMPLES.md)
+[AI Features](./AI-FEATURES.md)
+```
+
+### In `wiki/` (Generated)
+
+Links are automatically converted to Wiki format (no `.md` extension):
+
+```markdown
+[Quick Start](Quick-Start)
+[Examples](Examples)
+[AI Features](AI-Features)
+```
+
+### In Root `README.md`
+
+Point to `/docs`:
+
+```markdown
+[Quick Start](./docs/QUICKSTART.md)
+[Examples](./docs/EXAMPLES.md)
+[AI Features](./docs/AI-FEATURES.md)
+```
+
+## File Mapping
+
+| Source (`docs/`) | Wiki Output (`wiki/`) | Description |
+|------------------|-----------------------|-------------|
+| `QUICKSTART.md` | `Quick-Start.md` | Getting started |
+| `EXAMPLES.md` | `Examples.md` | Integration examples |
+| `AUTHENTICATION.md` | `Authentication.md` | Auth configuration |
+| `AI-FEATURES.md` | `AI-Features.md` | AI features guide |
+| `WIDGET-GUIDE.md` | `Widget-Bundle.md` | Widget bundles |
+| `MIGRATION-GUIDE.md` | `Migration-Guide.md` | Migration guide |
+| `API-REFERENCE.md` | `API-Reference.md` | TypeScript API |
+| `TROUBLESHOOTING.md` | `Troubleshooting.md` | Troubleshooting |
+| `BACKEND-API.md` | `Backend-Server.md` | Backend server |
+| `DEVELOPMENT.md` | `Development.md` | Development guide |
+| `NPM-PUBLISH.md` | `NPM-Publish.md` | Publishing workflow |
+| `REDIS-SETUP.md` | `Redis-Setup.md` | Redis setup |
+| `SERVER.md` | `Server.md` | Server docs |
+
+## Git Ignore Rules
+
+```gitignore
+# Wiki build output (keep templates only)
+wiki/*
+!wiki/Home.md
+!wiki/_Sidebar.md
+!wiki/README.md
+```
+
+This ensures:
+- ✅ Wiki templates (`Home.md`, `_Sidebar.md`, `README.md`) are committed
+- ✅ Generated wiki files (`*.md`) are NOT committed
+- ✅ Clean git history without build artifacts
+
+## Scripts
+
+### `scripts/wiki-build.sh`
+
+Builds `wiki/` directory from `docs/` source files.
+
+**What it does:**
+1. Copies `docs/*.md` → `wiki/*.md` with name mapping
+2. Converts markdown links to Wiki format (removes `.md` extensions)
+3. Preserves wiki templates (`Home.md`, `_Sidebar.md`)
+
+**Usage:**
+```bash
+./scripts/wiki-build.sh
+```
+
+### `scripts/wiki-deploy.sh`
+
+Deploys `wiki/` directory to GitHub Wiki repository.
+
+**What it does:**
+1. Runs `wiki-build.sh` to generate wiki files
+2. Clones GitHub Wiki repository (if not exists)
+3. Copies `wiki/*.md` to wiki repository
+4. Commits and pushes to GitHub Wiki
+
+**Usage:**
+```bash
+./scripts/wiki-deploy.sh "Update AI features documentation"
+```
+
+## Benefits
+
+### For Developers
+
+✅ Edit docs alongside code  
+✅ See docs in GitHub file browser  
+✅ Review documentation in pull requests  
+✅ Access docs offline  
+✅ Branch-specific documentation  
+
+### For Users
+
+✅ Browse docs in GitHub Wiki  
+✅ Search all documentation  
+✅ Formatted wiki pages  
+✅ Sidebar navigation  
+✅ Always up-to-date  
+
+### For Maintainers
+
+✅ Single source of truth - no duplication  
+✅ Automated wiki deployment  
+✅ No manual sync required  
+✅ Clean git history  
+✅ Easy to update  
+
+## Comparison with Alternatives
+
+### ❌ Root-Level Docs (Old Approach)
+
+```
+/
+├── QUICKSTART.md
+├── EXAMPLES.md
+├── AI-FEATURES.md
+└── ... (13 files at root)
+```
+
+**Problems:**
+- Cluttered root directory
+- Hard to distinguish docs from config files
+- No organization
+
+### ❌ Duplicate Docs (Old Wiki Approach)
+
+```
+/
+├── QUICKSTART.md (source)
+├── EXAMPLES.md (source)
+└── wiki/
+    ├── Quick-Start.md (duplicate!)
+    └── Examples.md (duplicate!)
+```
+
+**Problems:**
+- Duplication causes sync issues
+- Which is the source of truth?
+- Double maintenance burden
+
+### ✅ `/docs` + Generated `wiki/` (Current)
+
+```
+/
+├── docs/
+│   ├── QUICKSTART.md (source)
+│   └── EXAMPLES.md (source)
+└── wiki/
+    ├── Quick-Start.md (generated, gitignored)
+    └── Examples.md (generated, gitignored)
+```
+
+**Benefits:**
+- Single source of truth (`docs/`)
+- No duplication
+- Automated wiki generation
+- Clean git history
+
+## Maintenance
+
+### Regular Updates
+
+After each feature/bugfix:
+1. Update relevant docs in `docs/`
+2. Commit to repository
+3. Deploy to wiki: `./scripts/wiki-deploy.sh "Description"`
+
+### After Releases
+
+After releasing v1.1.0, v1.2.0, etc.:
+1. Update version numbers in docs
+2. Update `MIGRATION-GUIDE.md` with breaking changes
+3. Update `CHANGELOG.md`
+4. Deploy updated wiki
+
+## Statistics
+
+- **Source Files:** 13 markdown files in `docs/`
+- **Total Lines:** ~4,500+ lines of documentation
+- **Mermaid Diagrams:** 8 (3 in Authentication, 4 in AI Features, 1 in Widget)
+- **Code Examples:** 60+ with TypeScript/JavaScript/HTML/PHP/Liquid
+- **Languages:** TypeScript, JavaScript, Bash, JSON, HTML, PHP, Liquid
+
+## See Also
+
+- [WIKI-DEPLOYMENT.md](./WIKI-DEPLOYMENT.md) - Complete wiki deployment guide
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - How to contribute
+- [GitHub Wiki](https://github.com/Crownpeak/dqm-react-component/wiki) - Live wiki

package/data/I18N.md

@@ -0,0 +1,292 @@
+# Internationalization (i18n) Guide
+
+This document explains how to work with translations in the DQM React Component.
+
+## Overview
+
+The DQM component supports multiple languages with a modular translation system. Translations are organized by **namespace** (feature area) and **language**, making it easy to add new languages or update specific sections.
+
+## Supported Languages
+
+| Language | Code | Status |
+|----------|------|--------|
+| English | `en` | ✅ Default / Fallback |
+| German | `de` | ✅ Complete |
+| Spanish | `es` | ✅ Complete |
+
+### Regional Variants
+
+Regional variants (e.g., `de-AT`, `es-MX`) automatically fall back to their base language:
+
+- `de-AT` → `de` → `en`
+- `de-CH` → `de` → `en`
+- `es-MX` → `es` → `en`
+- `en-GB` → `en`
+
+## File Structure
+
+```
+src/i18n/
+├── index.ts              # Main configuration, combines all namespaces
+├── common/               # Shared UI strings
+│   ├── en.ts
+│   ├── de.ts
+│   ├── es.ts
+│   └── index.ts
+├── sidebar/              # DQM sidebar strings (~100 keys)
+│   ├── en.ts
+│   ├── de.ts
+│   ├── es.ts
+│   └── index.ts
+├── auth/                 # Authentication strings
+│   ├── en.ts
+│   ├── de.ts
+│   ├── es.ts
+│   └── index.ts
+└── demo/                 # Demo app strings (dev only)
+    ├── en.ts
+    ├── de.ts
+    ├── es.ts
+    └── index.ts
+```
+
+## Adding a New Language
+
+### Step 1: Create translation files
+
+For each namespace, create a new file with your language code:
+
+```typescript
+// src/i18n/common/fr.ts
+export const common = {
+  language: 'Langue',
+  language_switch_label: 'Langue',
+  // ... copy all keys from en.ts and translate
+} as const;
+```
+
+### Step 2: Export from namespace index
+
+```typescript
+// src/i18n/common/index.ts
+export { common as en } from './en';
+export { common as de } from './de';
+export { common as es } from './es';
+export { common as fr } from './fr';  // Add this line
+```
+
+### Step 3: Add to main configuration
+
+```typescript
+// src/i18n/index.ts
+import * as common from './common';
+// ...
+
+const resources = {
+  en: { common: common.en, /* ... */ },
+  de: { common: common.de, /* ... */ },
+  es: { common: common.es, /* ... */ },
+  fr: { common: common.fr, /* ... */ },  // Add this
+} as const;
+```
+
+### Step 4: Update locale.ts
+
+```typescript
+// src/locale.ts
+const SUPPORTED_LOCALES = ['en', 'de', 'es', 'fr'] as const;
+```
+
+### Step 5: Add language name translations
+
+In **each** language file's `common` namespace, add the new language name:
+
+```typescript
+// common/en.ts
+language_fr: 'French',
+
+// common/de.ts
+language_fr: 'Französisch',
+
+// common/fr.ts
+language_fr: 'Français',
+```
+
+## Adding New Translation Keys
+
+### Step 1: Add to English (fallback) first
+
+```typescript
+// src/i18n/sidebar/en.ts
+export const sidebar = {
+  // ... existing keys
+  my_new_feature: 'My new feature',
+} as const;
+```
+
+### Step 2: Add to all other languages
+
+```typescript
+// src/i18n/sidebar/de.ts
+my_new_feature: 'Meine neue Funktion',
+
+// src/i18n/sidebar/es.ts
+my_new_feature: 'Mi nueva función',
+```
+
+### Step 3: Use in components
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+const MyComponent = () => {
+  const { t } = useTranslation('sidebar');
+  return <span>{t('my_new_feature')}</span>;
+};
+```
+
+## Interpolation
+
+Use `{{variable}}` for dynamic values:
+
+```typescript
+// Translation file
+translation_progress: '{{done}} / {{total}} checkpoints',
+
+// Usage
+t('sidebar:translation_progress', { done: 5, total: 10 })
+// Output: "5 / 10 checkpoints"
+```
+
+## Namespaces
+
+| Namespace | Purpose | Used in |
+|-----------|---------|---------|
+| `common` | Shared strings (language names, buttons) | All components |
+| `sidebar` | Main DQM sidebar UI | `DQMSidebar.tsx` |
+| `auth` | Login/authentication | `DQMLogin.tsx` |
+| `demo` | Demo application (dev only) | `App.tsx` |
+
+### Using namespaces
+
+```tsx
+// Single namespace
+const { t } = useTranslation('sidebar');
+t('title')  // Uses sidebar:title
+
+// Multiple namespaces
+const { t } = useTranslation(['sidebar', 'common']);
+t('sidebar:title')
+t('common:logout')
+
+// With namespace prefix
+t('sidebar:translation_progress', { done: 5, total: 10 })
+```
+
+## Type Safety
+
+Translation keys are typed. TypeScript will warn if you use a non-existent key:
+
+```typescript
+import type { SidebarTranslationKeys } from './i18n';
+
+// This is type-safe
+const key: SidebarTranslationKeys = 'title';  // ✅
+const bad: SidebarTranslationKeys = 'nonexistent';  // ❌ Type error
+```
+
+## Best Practices
+
+1. **Always add to English first** – English is the fallback language
+2. **Keep keys descriptive** – Use `translation_progress` not `tp`
+3. **Group related keys** – Use comments to organize sections
+4. **Test all languages** – Switch languages in the UI to verify
+5. **Don't hardcode strings** – All user-visible text should be translated
+
+## Changing the User's Language
+
+The library exports the i18next instance for programmatic language control:
+
+```tsx
+import { i18n, SUPPORTED_LOCALES } from '@crownpeak/dqm-react-component';
+
+// Change language programmatically
+i18n.changeLanguage('de');
+
+// Get current language
+const currentLang = i18n.language;
+
+// Check supported locales
+console.log(SUPPORTED_LOCALES); // ['en', 'de', 'es']
+```
+
+### Handling Regional Variants
+
+```tsx
+import { resolveLanguage, normalizeLocale } from '@crownpeak/dqm-react-component';
+
+// Resolve regional variant to base language
+resolveLanguage('de-AT');  // Returns 'de'
+resolveLanguage('es-MX');  // Returns 'es'
+resolveLanguage('fr');     // Returns 'en' (fallback)
+
+// Validate and normalize locale input
+normalizeLocale('de-AT');  // Returns 'de'
+normalizeLocale('fr');     // Returns null (unsupported)
+```
+
+### Using the LanguageSwitch Component
+
+```tsx
+import { LanguageSwitch } from '@crownpeak/dqm-react-component';
+
+// Built-in language switcher (used in sidebar footer)
+<LanguageSwitch />
+```
+
+### Listening for Language Changes
+
+```tsx
+import { i18n } from '@crownpeak/dqm-react-component';
+import { useEffect } from 'react';
+
+function MyComponent() {
+  useEffect(() => {
+    const handleLanguageChange = (lng: string) => {
+      console.log('DQM language changed to:', lng);
+    };
+    
+    i18n.on('languageChanged', handleLanguageChange);
+    return () => i18n.off('languageChanged', handleLanguageChange);
+  }, []);
+  
+  return <div>Current: {i18n.language}</div>;
+}
+```
+
+## Troubleshooting
+
+### Missing translation shows key name
+
+If you see `sidebar:my_key` instead of the translation:
+- Check the key exists in all language files
+- Verify the namespace is correct
+- Ensure the language file is exported in `index.ts`
+
+### Regional variant not working
+
+Regional variants (e.g., `de-AT`) fall back to the base language. If you need region-specific translations:
+
+1. Create `de-AT.ts` alongside `de.ts`
+2. Export it in the namespace's `index.ts`
+3. Add to `REGIONAL_FALLBACKS` in `src/i18n/index.ts`
+
+### TypeScript errors on translation keys
+
+Ensure all translation files export `as const` for proper type inference:
+
+```typescript
+export const sidebar = {
+  // ...
+} as const;  // ← Important!
+```

package/data/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.
+