@seamware/odrl-policy-editor 1.5.0-PRE-53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,782 @@
1
+ # ODRL PAP Frontend
2
+
3
+ [![npm](https://img.shields.io/npm/v/@seamware/odrl-policy-editor)](https://www.npmjs.com/package/@seamware/odrl-policy-editor)
4
+
5
+ A React-based frontend for the ODRL Policy Administration Point (PAP). It
6
+ provides a visual, form-driven policy editor that guides users through creating
7
+ [ODRL](https://www.w3.org/TR/odrl-model/) policies step by step.
8
+
9
+ The editor can be used in two ways:
10
+
11
+ 1. **Standalone SPA** — a full single-page application with page routing,
12
+ served via Nginx or any static file server.
13
+ 2. **Embeddable Web Component** — the `<odrl-policy-editor>` custom element
14
+ can be dropped into any HTML page (e.g., BAE-Marketplace, FDSC-Dashboard)
15
+ with Shadow DOM style isolation and zero framework dependencies on the
16
+ host page.
17
+
18
+ ---
19
+
20
+ ## Table of Contents
21
+
22
+ - [Installation](#installation)
23
+ - [Quick Integration](#quick-integration)
24
+ - [Docker](#docker)
25
+ - [Integration Guides](#integration-guides)
26
+ - [Prerequisites](#prerequisites)
27
+ - [Quick Start (Development)](#quick-start-development)
28
+ - [Standalone SPA Usage](#standalone-spa-usage)
29
+ - [Building for Production](#building-for-production)
30
+ - [Docker Deployment](#docker-deployment)
31
+ - [Configuration](#configuration)
32
+ - [Embedding as a Web Component](#embedding-as-a-web-component)
33
+ - [Building the Web Component Bundle](#building-the-web-component-bundle)
34
+ - [Basic Usage](#basic-usage)
35
+ - [HTML Attributes](#html-attributes)
36
+ - [JavaScript Properties](#javascript-properties)
37
+ - [Custom Events](#custom-events)
38
+ - [Full Embedding Example](#full-embedding-example)
39
+ - [Theming](#theming)
40
+ - [Light and Dark Mode](#light-and-dark-mode)
41
+ - [Custom Theme Properties](#custom-theme-properties)
42
+ - [Theming in Standalone Mode](#theming-in-standalone-mode)
43
+ - [Theming in Embedded Mode](#theming-in-embedded-mode)
44
+ - [Internationalization (i18n)](#internationalization-i18n)
45
+ - [Changing the Locale](#changing-the-locale)
46
+ - [Providing Custom Translations](#providing-custom-translations)
47
+ - [Translation Keys Reference](#translation-keys-reference)
48
+ - [Authentication](#authentication)
49
+ - [Standalone Mode Authentication](#standalone-mode-authentication)
50
+ - [Embedded Mode Authentication](#embedded-mode-authentication)
51
+ - [API Base URL Resolution](#api-base-url-resolution)
52
+ - [Testing](#testing)
53
+ - [Regenerating the API Client](#regenerating-the-api-client)
54
+
55
+ ---
56
+
57
+ ## Installation
58
+
59
+ Install the embeddable Web Component via npm:
60
+
61
+ ```bash
62
+ npm install @seamware/odrl-policy-editor
63
+ ```
64
+
65
+ Or load it directly from a CDN — no build step required:
66
+
67
+ ```html
68
+ <!-- unpkg -->
69
+ <script type="module" src="https://unpkg.com/@seamware/odrl-policy-editor@latest"></script>
70
+
71
+ <!-- jsDelivr (alternative) -->
72
+ <script type="module" src="https://cdn.jsdelivr.net/npm/@seamware/odrl-policy-editor@latest"></script>
73
+ ```
74
+
75
+ ---
76
+
77
+ ## Quick Integration
78
+
79
+ Drop this snippet into any HTML page to get a working policy editor:
80
+
81
+ ```html
82
+ <!DOCTYPE html>
83
+ <html lang="en">
84
+ <head>
85
+ <meta charset="UTF-8" />
86
+ <script type="module" src="https://unpkg.com/@seamware/odrl-policy-editor@latest"></script>
87
+ </head>
88
+ <body>
89
+ <odrl-policy-editor
90
+ api-base-url="https://your-pap-backend.example.com"
91
+ mode="create"
92
+ theme="light"
93
+ locale="en"
94
+ ></odrl-policy-editor>
95
+ <script>
96
+ document.querySelector('odrl-policy-editor')
97
+ .addEventListener('policy-created', (e) => console.log('Created:', e.detail.id));
98
+ </script>
99
+ </body>
100
+ </html>
101
+ ```
102
+
103
+ See [Embedding as a Web Component](#embedding-as-a-web-component) for full
104
+ attribute/property/event documentation.
105
+
106
+ ---
107
+
108
+ ## Docker
109
+
110
+ A pre-built frontend Docker image is available:
111
+
112
+ ```bash
113
+ docker pull quay.io/fiware/odrl-pap-frontend:<version>
114
+ ```
115
+
116
+ Run the container with the PAP backend URL:
117
+
118
+ ```bash
119
+ docker run -p 8080:80 \
120
+ -e PAP_BACKEND_URL=http://odrl-pap:8080 \
121
+ quay.io/fiware/odrl-pap-frontend:<version>
122
+ ```
123
+
124
+ See [Docker Deployment](#docker-deployment) for full configuration details.
125
+
126
+ ---
127
+
128
+ ## Integration Guides
129
+
130
+ Detailed, step-by-step guides for embedding the Web Component in specific
131
+ platforms:
132
+
133
+ - **[FDSC-Dashboard (Vue 3 + Vuetify)](docs/integration-fdsc-dashboard.md)** —
134
+ Vue wrapper component with OIDC auth token and Vuetify theme bridging
135
+ - **[BAE Logic Proxy](docs/integration-bae-logic-proxy.md)** —
136
+ CDN and npm integration options for the BAE marketplace portal
137
+ - **[Generic Integration](docs/integration-generic.md)** —
138
+ Vanilla JS, React, Angular, Vue 2/3, Svelte, SSR, security (CSP), and
139
+ performance optimization
140
+
141
+ Working examples are available in the [`examples/`](examples/) directory:
142
+
143
+ | Example | Description |
144
+ |---------|-------------|
145
+ | [`vanilla-integration/`](examples/vanilla-integration/) | Standalone HTML page with CDN loading and a config panel |
146
+ | [`vue-integration/`](examples/vue-integration/) | Copy-pasteable Vue 3 wrapper component |
147
+
148
+ ---
149
+
150
+ ## Prerequisites
151
+
152
+ - **Node.js** >= 18 and **npm** >= 9
153
+ - A running instance of the ODRL PAP backend (default: `http://localhost:8080`)
154
+
155
+ ---
156
+
157
+ ## Quick Start (Development)
158
+
159
+ The development server provides hot module replacement (HMR) so that changes to
160
+ source files are reflected in the browser immediately, and a built-in proxy that
161
+ forwards API requests to the backend.
162
+
163
+ ```bash
164
+ # 1. Install dependencies
165
+ cd frontend
166
+ npm install
167
+
168
+ # 2. Copy the environment template and adjust if needed
169
+ cp .env.example .env
170
+ # Edit .env to set VITE_API_PROXY_TARGET to your backend URL (default: http://localhost:8080)
171
+
172
+ # 3. Start the Vite dev server
173
+ npm run dev
174
+ ```
175
+
176
+ The editor opens at **http://localhost:5173**. API calls to `/mappings`,
177
+ `/policy`, and `/validate` are proxied to the backend specified by
178
+ `VITE_API_PROXY_TARGET` in `.env`.
179
+
180
+ ### Starting the Backend
181
+
182
+ If you do not already have a backend running, start one from the repository root:
183
+
184
+ ```bash
185
+ # From the repository root
186
+ ./mvnw quarkus:dev
187
+ ```
188
+
189
+ This starts the PAP backend on `http://localhost:8080` with live-reload.
190
+
191
+ ---
192
+
193
+ ## Standalone SPA Usage
194
+
195
+ The standalone application renders three routes:
196
+
197
+ | Route | Description |
198
+ |-------------|---------------------------------------------|
199
+ | `/` | Policy list — view, edit, and delete policies |
200
+ | `/new` | Create a new policy via the guided builder |
201
+ | `/edit/:id` | Edit an existing policy by its ID |
202
+
203
+ ### Building for Production
204
+
205
+ ```bash
206
+ npm run build
207
+ ```
208
+
209
+ This creates a `dist/` directory with optimized static assets ready to deploy
210
+ behind any HTTP server (Nginx, Apache, Caddy, a CDN, etc.). The server must be
211
+ configured for SPA routing (all unknown paths serve `index.html`).
212
+
213
+ ### Docker Deployment
214
+
215
+ A multi-stage `Dockerfile` is provided. The container includes an Nginx reverse
216
+ proxy that forwards API requests to the PAP backend, so the browser never makes
217
+ cross-origin requests (no CORS issues).
218
+
219
+ ```bash
220
+ # 1. Build the image
221
+ docker build -t odrl-pap-frontend .
222
+
223
+ # 2. Run the container — set PAP_BACKEND_URL to the backend's internal address
224
+ docker run -p 8080:80 \
225
+ -e PAP_BACKEND_URL=http://odrl-pap:8080 \
226
+ odrl-pap-frontend
227
+ ```
228
+
229
+ The frontend is served at `http://localhost:8080`. API requests to `/policy`,
230
+ `/mappings`, and `/validate` are transparently proxied to the backend specified
231
+ by `PAP_BACKEND_URL`.
232
+
233
+ The container uses Nginx with:
234
+
235
+ - **API reverse proxy** — forwards `/policy`, `/mappings`, `/validate` to the
236
+ backend, avoiding CORS issues
237
+ - **SPA fallback** — `try_files $uri $uri/ /index.html`
238
+ - **Gzip compression** — enabled for JS, CSS, JSON, SVG
239
+ - **Cache headers** — hashed assets cached for 1 year; `index.html` never cached
240
+ - **Health check** — `GET /healthz` returns `200 OK`
241
+
242
+ The `PAP_BACKEND_URL` environment variable is injected **at container startup**
243
+ via `envsubst` into the Nginx config, so a single image can be reused across
244
+ environments without rebuilding.
245
+
246
+ ### Configuration
247
+
248
+ Environment variables are defined in a `.env` file (copy `.env.example` as a
249
+ starting point).
250
+
251
+ | Variable | Purpose | Default |
252
+ |------------------------|------------------------------------------------------|------------------------|
253
+ | `VITE_API_PROXY_TARGET`| Backend URL used by the Vite dev-server proxy | `http://localhost:8080` |
254
+ | `PAP_BACKEND_URL` | Backend URL for the Nginx reverse proxy (Docker) | _(required in Docker)_ |
255
+ | `VITE_API_BASE_URL` | Override API base URL in the browser (rarely needed) | `""` (empty = proxy) |
256
+ | `VITE_ODRL_CONTEXT` | Default `@context` for new policies (JSON string) | `{"odrl":"http://www.w3.org/ns/odrl/2/"}` |
257
+
258
+ - **Development mode** — the Vite dev server proxies `/mappings`, `/policy`,
259
+ and `/validate` to the backend specified by `VITE_API_PROXY_TARGET`.
260
+ - **Docker / Production** — Nginx reverse-proxies API paths to `PAP_BACKEND_URL`.
261
+ The frontend uses relative paths (empty base URL) so all requests go through
262
+ the same origin, avoiding CORS issues entirely.
263
+ - **`VITE_API_BASE_URL`** — only needed if the frontend must call a different
264
+ origin than the Nginx proxy (e.g., an external API gateway). In the normal
265
+ proxy setup this variable should be left unset.
266
+
267
+ ### Preview Mode
268
+
269
+ Preview mode builds the production bundle and serves it locally:
270
+
271
+ ```bash
272
+ npm run build
273
+ npm run preview
274
+ ```
275
+
276
+ The preview server starts at **http://localhost:4173**.
277
+
278
+ ---
279
+
280
+ ## Embedding as a Web Component
281
+
282
+ The policy editor can be embedded in any HTML page as a standard
283
+ [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
284
+ The `<odrl-policy-editor>` custom element uses Shadow DOM for complete
285
+ style isolation — host-page CSS does not leak in, and editor styles do not
286
+ leak out.
287
+
288
+ ### Building the Web Component Bundle
289
+
290
+ ```bash
291
+ npm run build:component
292
+ ```
293
+
294
+ This produces a single self-contained ES module at
295
+ `dist-component/odrl-policy-editor.js`. The bundle inlines all dependencies
296
+ (React, Bootstrap CSS, theme CSS) so there are **zero external dependencies**.
297
+
298
+ ### Basic Usage
299
+
300
+ ```html
301
+ <!-- Load the bundle -->
302
+ <script type="module" src="path/to/odrl-policy-editor.js"></script>
303
+
304
+ <!-- Use the element -->
305
+ <odrl-policy-editor
306
+ api-base-url="https://pap-api.example.com"
307
+ auth-token="eyJhbGciOiJSUzI1NiIs..."
308
+ mode="create"
309
+ theme="light"
310
+ locale="en"
311
+ ></odrl-policy-editor>
312
+ ```
313
+
314
+ ### HTML Attributes
315
+
316
+ All configuration is passed via standard HTML attributes. Changing an attribute
317
+ at runtime triggers a re-render automatically.
318
+
319
+ | Attribute | Description | Default |
320
+ |-----------------|-----------------------------------------------|------------|
321
+ | `api-base-url` | PAP API base URL | `""` |
322
+ | `auth-token` | Bearer token for API authentication | `null` |
323
+ | `mode` | `"create"` or `"edit"` | `"create"` |
324
+ | `policy-id` | Policy ID to load (required when `mode="edit"`) | `null` |
325
+ | `theme` | `"light"` or `"dark"` | `"light"` |
326
+ | `locale` | Language code (e.g., `"en"`, `"de"`) | `"en"` |
327
+ | `policy-context`| Default `@context` for new policies (JSON string) | `{"odrl":"http://www.w3.org/ns/odrl/2/"}` |
328
+
329
+ ```javascript
330
+ // Attributes can be changed at runtime
331
+ const editor = document.querySelector('odrl-policy-editor');
332
+ editor.setAttribute('theme', 'dark');
333
+ editor.setAttribute('locale', 'de');
334
+ editor.setAttribute('api-base-url', 'https://new-api.example.com');
335
+ ```
336
+
337
+ ### JavaScript Properties
338
+
339
+ For richer configuration that cannot be expressed as string attributes, use
340
+ JavaScript properties on the element:
341
+
342
+ | Property | Type | Description |
343
+ |---------------|------------------------------|------------------------------------------------------|
344
+ | `i18nStrings` | `DeepPartial<I18nStrings>` | Partial i18n overrides (deep-merged with defaults) |
345
+ | `themeConfig` | `Partial<ThemeConfig>` | Partial theme CSS custom property overrides |
346
+ | `template` | `PolicyTemplate` | Pre-fills the form and optionally locks fields |
347
+ | `policyContext` | `Record<string, string>` | Default `@context` for new policies (takes precedence over attribute) |
348
+
349
+ ```javascript
350
+ const editor = document.querySelector('odrl-policy-editor');
351
+
352
+ // Override specific translation strings
353
+ editor.i18nStrings = {
354
+ policyBuilder: { title: 'Richtlinien-Editor' },
355
+ common: { save: 'Speichern', cancel: 'Abbrechen' },
356
+ };
357
+
358
+ // Override specific theme properties
359
+ editor.themeConfig = {
360
+ 'odrl-primary-color': '#1a73e8',
361
+ 'odrl-secondary-color': '#e8710a',
362
+ };
363
+
364
+ // Pre-fill and constrain the editor with a template
365
+ editor.template = {
366
+ id: 'dome-access',
367
+ name: 'DOME Marketplace Access',
368
+ description: 'Grants access to a DOME resource',
369
+ category: 'DOME',
370
+ skeleton: {
371
+ '@context': 'http://www.w3.org/ns/odrl/2/',
372
+ '@type': 'odrl:Policy',
373
+ 'odrl:permission': { 'odrl:action': 'odrl:use' },
374
+ },
375
+ editableFields: [
376
+ { path: 'odrl:permission.odrl:target', label: 'Target Resource' },
377
+ ],
378
+ lockedFields: ['odrl:permission.odrl:action'],
379
+ };
380
+ ```
381
+
382
+ ### Custom Events
383
+
384
+ The Web Component communicates with the host page via
385
+ [Custom Events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent).
386
+ Events bubble and cross Shadow DOM boundaries (`composed: true`).
387
+
388
+ | Event | Detail payload | Fired when |
389
+ |--------------------|---------------------------------------------|----------------------------------|
390
+ | `policy-created` | `{ policy: OdrlPolicyJson, id: string }` | A new policy is saved |
391
+ | `policy-updated` | `{ policy: OdrlPolicyJson, id: string }` | An existing policy is updated |
392
+ | `policy-validated` | `{ result: ValidationResponse }` | Policy validation completes |
393
+ | `editor-cancelled` | `{}` | The user clicks Cancel |
394
+
395
+ ```javascript
396
+ const editor = document.querySelector('odrl-policy-editor');
397
+
398
+ editor.addEventListener('policy-created', (e) => {
399
+ console.log('New policy saved:', e.detail.id);
400
+ console.log('Policy JSON:', e.detail.policy);
401
+ });
402
+
403
+ editor.addEventListener('policy-validated', (e) => {
404
+ const allowed = e.detail.result.allowed;
405
+ console.log('Validation result:', allowed ? 'ALLOWED' : 'DENIED');
406
+ });
407
+
408
+ editor.addEventListener('editor-cancelled', () => {
409
+ // Hide the editor or navigate away
410
+ document.querySelector('odrl-policy-editor').remove();
411
+ });
412
+ ```
413
+
414
+ ### Full Embedding Example
415
+
416
+ A complete working example is available at `examples/embed-example.html`. To run
417
+ it:
418
+
419
+ ```bash
420
+ cd frontend
421
+ npm install
422
+ npm run build:component
423
+ npx serve .
424
+ # Open http://localhost:3000/examples/embed-example.html
425
+ ```
426
+
427
+ The example demonstrates:
428
+
429
+ - Attribute-driven configuration (theme, locale, API URL)
430
+ - Runtime attribute changes via a control panel
431
+ - Custom event logging
432
+ - i18n string overrides via the `i18nStrings` JS property
433
+ - Theme overrides via the `themeConfig` JS property
434
+
435
+ ---
436
+
437
+ ## Theming
438
+
439
+ The frontend uses CSS custom properties (CSS variables) for all visual
440
+ styling. This allows full visual customization without modifying source code.
441
+
442
+ ### Light and Dark Mode
443
+
444
+ Two built-in presets are available: **light** (default) and **dark**.
445
+
446
+ **Standalone mode** — the `ThemeProvider` component wraps the application and
447
+ applies CSS custom properties on `document.documentElement`.
448
+
449
+ **Embedded mode** — set the `theme` attribute on the custom element:
450
+
451
+ ```html
452
+ <!-- Light mode (default) -->
453
+ <odrl-policy-editor theme="light"></odrl-policy-editor>
454
+
455
+ <!-- Dark mode -->
456
+ <odrl-policy-editor theme="dark"></odrl-policy-editor>
457
+ ```
458
+
459
+ ### Custom Theme Properties
460
+
461
+ Both presets define the following CSS custom properties. Override any of them
462
+ to match your brand:
463
+
464
+ | CSS Custom Property | Description | Light Default | Dark Default |
465
+ |-----------------------------|-----------------------------------|----------------------|----------------------|
466
+ | `--odrl-primary-color` | Primary brand color | `#0B2B40` | `#1a4a6b` |
467
+ | `--odrl-secondary-color` | Accent / highlight color | `#F07D00` | `#F07D00` |
468
+ | `--odrl-bg-color` | Page / container background | `#FFFFFF` | `#1a1a2e` |
469
+ | `--odrl-text-color` | Default text color | `#333333` | `#e0e0e0` |
470
+ | `--odrl-text-muted` | Muted / secondary text | `#6c757d` | `#adb5bd` |
471
+ | `--odrl-card-bg` | Card and panel background | `#f8f9fa` | `#16213e` |
472
+ | `--odrl-border-color` | Default border color | `#dee2e6` | `#2a2a4a` |
473
+ | `--odrl-font-family` | Base font family | `'Lato', sans-serif` | `'Lato', sans-serif` |
474
+ | `--odrl-border-radius` | Default border radius | `0.375rem` | `0.375rem` |
475
+ | `--odrl-section-header-bg` | Section / step header background | `#e9ecef` | `#0f3460` |
476
+ | `--odrl-success-color` | Success indicator | `#198754` | `#20c997` |
477
+ | `--odrl-danger-color` | Danger / error indicator | `#dc3545` | `#e74c3c` |
478
+ | `--odrl-info-color` | Info indicator | `#0dcaf0` | `#17a2b8` |
479
+ | `--odrl-card-shadow` | Card drop shadow | `0 0.125rem 0.25rem rgba(0,0,0,0.075)` | `0 0.125rem 0.25rem rgba(0,0,0,0.3)` |
480
+
481
+ ### Theming in Standalone Mode
482
+
483
+ In standalone mode the `ThemeProvider` applies CSS custom properties to the
484
+ document root. You can override them in your own stylesheet:
485
+
486
+ ```css
487
+ :root {
488
+ --odrl-primary-color: #1a73e8;
489
+ --odrl-secondary-color: #e8710a;
490
+ --odrl-font-family: 'Inter', sans-serif;
491
+ }
492
+ ```
493
+
494
+ ### Theming in Embedded Mode
495
+
496
+ In embedded mode, use the `themeConfig` JavaScript property to override
497
+ specific properties. Overrides are merged on top of the selected preset:
498
+
499
+ ```javascript
500
+ const editor = document.querySelector('odrl-policy-editor');
501
+
502
+ // Start from dark preset, then override specific values
503
+ editor.setAttribute('theme', 'dark');
504
+ editor.themeConfig = {
505
+ 'odrl-primary-color': '#1a73e8',
506
+ 'odrl-bg-color': '#121212',
507
+ 'odrl-card-bg': '#1e1e1e',
508
+ };
509
+ ```
510
+
511
+ Because the Web Component uses Shadow DOM, your overrides only affect the
512
+ editor — they will not interfere with the host page's styles.
513
+
514
+ ---
515
+
516
+ ## Internationalization (i18n)
517
+
518
+ The frontend ships with English (`en`) as the default and only built-in locale.
519
+ The i18n system supports runtime locale switching and partial string overrides,
520
+ making it easy to add new languages without rebuilding.
521
+
522
+ ### Changing the Locale
523
+
524
+ **Standalone mode** — the `I18nProvider` accepts a `locale` prop. To add a new
525
+ language, pass the locale code and a partial or full set of translated strings:
526
+
527
+ ```tsx
528
+ <I18nProvider locale="de" strings={germanStrings}>
529
+ <App />
530
+ </I18nProvider>
531
+ ```
532
+
533
+ **Embedded mode** — set the `locale` attribute on the custom element:
534
+
535
+ ```html
536
+ <odrl-policy-editor locale="de"></odrl-policy-editor>
537
+ ```
538
+
539
+ The `locale` attribute can be changed at runtime and the UI will re-render.
540
+
541
+ ### Providing Custom Translations
542
+
543
+ Translations are supplied as a nested object matching the structure of the
544
+ English defaults. You only need to provide the keys you want to override —
545
+ missing keys fall back to English automatically (deep merge).
546
+
547
+ **Embedded mode** — use the `i18nStrings` JavaScript property:
548
+
549
+ ```javascript
550
+ const editor = document.querySelector('odrl-policy-editor');
551
+ editor.setAttribute('locale', 'de');
552
+ editor.i18nStrings = {
553
+ common: {
554
+ save: 'Speichern',
555
+ cancel: 'Abbrechen',
556
+ delete: 'Loschen',
557
+ loading: 'Wird geladen...',
558
+ },
559
+ policyBuilder: {
560
+ title: 'Richtlinien-Editor',
561
+ stepTarget: 'Ziel',
562
+ stepTargetHelp: 'Definieren Sie, auf welche Ressource diese Richtlinie anwendbar ist.',
563
+ stepAssignee: 'Berechtigter',
564
+ stepAssigneeHelp: 'Geben Sie an, wem die Berechtigung erteilt oder verweigert wird.',
565
+ stepAction: 'Aktion',
566
+ stepActionHelp: 'Wahlen Sie die erlaubte oder verbotene Operation.',
567
+ stepConstraints: 'Einschrankungen',
568
+ stepConstraintsHelp: 'Fugen Sie Bedingungen hinzu, die erfullt sein mussen.',
569
+ },
570
+ policyList: {
571
+ title: 'Richtlinien',
572
+ newPolicy: 'Neue Richtlinie',
573
+ },
574
+ };
575
+ ```
576
+
577
+ To reset to English defaults, set `i18nStrings` to `undefined`:
578
+
579
+ ```javascript
580
+ editor.i18nStrings = undefined;
581
+ ```
582
+
583
+ ### Translation Keys Reference
584
+
585
+ The i18n system organizes strings by UI section. Below are the top-level
586
+ sections with representative keys (see `src/i18n/en.ts` for the complete
587
+ reference):
588
+
589
+ | Section | Description | Example Keys |
590
+ |----------------------|------------------------------------|-------------------------------------------------|
591
+ | `common` | Shared labels and buttons | `save`, `cancel`, `delete`, `loading`, `search` |
592
+ | `policyBuilder` | Policy builder wizard | `title`, `stepTarget`, `stepAction`, `stepConstraints` |
593
+ | `targetEditor` | Target selection UI | `simpleTarget`, `enterTargetUrl`, `refinementsTitle` |
594
+ | `assigneeEditor` | Assignee selection UI | `simpleAssignee`, `enterAssigneeId`, `refinementsTitle` |
595
+ | `constraintBuilder` | Constraint editing | `addConstraint`, `groupingAnd`, `groupingOr` |
596
+ | `policySummary` | Policy summary panel | `title`, `showJson`, `humanSummary` |
597
+ | `validationEditor` | Validation request builder | `method`, `host`, `path`, `runValidation` |
598
+ | `validationResult` | Validation result display | `allowed`, `denied`, `explanationTitle` |
599
+ | `policyList` | Policy list page | `title`, `newPolicy`, `confirmDelete` |
600
+ | `policyEditor` | Editor page chrome | `editTitle`, `newTitle`, `tabBuilder` |
601
+ | `namespacedDropdown` | Grouped dropdown component | `noResults`, `filterPlaceholder` |
602
+ | `templateMode` | Template mode banner and labels | `banner`, `lockedFieldTooltip`, `lockedBadge` |
603
+
604
+ ---
605
+
606
+ ## Authentication
607
+
608
+ The frontend does **not** include a login page or user management UI.
609
+ Authentication is expected to be handled externally (e.g., by an API gateway,
610
+ an identity provider, or the embedding application). The frontend simply
611
+ attaches a Bearer token to every API request when one is available.
612
+
613
+ ### Standalone Mode Authentication
614
+
615
+ In standalone mode, the frontend reads the token from the browser's
616
+ `localStorage`:
617
+
618
+ ```javascript
619
+ // Set the token (e.g., after your external login flow completes)
620
+ localStorage.setItem('authToken', 'eyJhbGciOiJSUzI1NiIs...');
621
+
622
+ // Remove the token (logout)
623
+ localStorage.removeItem('authToken');
624
+ ```
625
+
626
+ Once set, the token is included as an `Authorization: Bearer <token>` header
627
+ on every API request. If no token is present, requests are sent without an
628
+ authorization header.
629
+
630
+ A typical integration pattern:
631
+
632
+ 1. The user authenticates with your identity provider (Keycloak, Auth0, etc.).
633
+ 2. Your login callback stores the access token:
634
+ `localStorage.setItem('authToken', accessToken)`.
635
+ 3. Navigate to the ODRL PAP frontend — API requests are now authenticated.
636
+ 4. On logout, remove the token: `localStorage.removeItem('authToken')`.
637
+
638
+ ### Embedded Mode Authentication
639
+
640
+ When using the `<odrl-policy-editor>` Web Component, pass the token via the
641
+ `auth-token` HTML attribute:
642
+
643
+ ```html
644
+ <odrl-policy-editor
645
+ api-base-url="https://pap-api.example.com"
646
+ auth-token="eyJhbGciOiJSUzI1NiIs..."
647
+ ></odrl-policy-editor>
648
+ ```
649
+
650
+ The attribute-supplied token takes precedence over any token in `localStorage`.
651
+ This allows the embedding application to manage authentication entirely on its
652
+ own and simply hand the token down.
653
+
654
+ ```javascript
655
+ // Update the token at runtime (e.g., after a token refresh)
656
+ const editor = document.querySelector('odrl-policy-editor');
657
+ editor.setAttribute('auth-token', newAccessToken);
658
+ ```
659
+
660
+ ### API Base URL Resolution
661
+
662
+ The API base URL is resolved from multiple sources (highest priority first):
663
+
664
+ | Priority | Source | Context |
665
+ |----------|--------------------------------------------|-----------------------|
666
+ | 1 | `configureApi(baseUrl, token)` (programmatic) | Web Component mode |
667
+ | 2 | `window.__ENV__.API_BASE_URL` (runtime) | Docker `envsubst` |
668
+ | 3 | `import.meta.env.VITE_API_BASE_URL` (build-time) | Static builds |
669
+ | 4 | Empty string (relative paths) | Dev proxy / Nginx reverse proxy |
670
+
671
+ In the recommended Docker deployment, the base URL resolves to an empty string
672
+ (priority 4). API requests use relative paths (`/policy`, `/mappings`,
673
+ `/validate`) and are proxied by Nginx to the backend configured via
674
+ `PAP_BACKEND_URL`. This avoids CORS issues entirely because the browser sees
675
+ all traffic going to a single origin.
676
+
677
+ ---
678
+
679
+ ## Policy Context (`@context`) Configuration
680
+
681
+ New policies are created with a default JSON-LD `@context`. The PAP backend
682
+ expects the context as a **namespaced object**:
683
+
684
+ ```json
685
+ {
686
+ "@context": {
687
+ "odrl": "http://www.w3.org/ns/odrl/2/"
688
+ }
689
+ }
690
+ ```
691
+
692
+ The default context can be overridden at multiple levels. Resolution order
693
+ (highest priority first):
694
+
695
+ | Priority | Source | Context |
696
+ |----------|----------------------------------------------|----------------------------------|
697
+ | 1 | `policyContext` JS property on the Web Component | Embedded mode (programmatic) |
698
+ | 2 | `policy-context` HTML attribute (JSON string) | Embedded mode (declarative) |
699
+ | 3 | `window.__ENV__.ODRL_CONTEXT` (runtime JSON) | Docker `envsubst` |
700
+ | 4 | `import.meta.env.VITE_ODRL_CONTEXT` (build-time) | Static builds |
701
+ | 5 | `{ "odrl": "http://www.w3.org/ns/odrl/2/" }` | Built-in default |
702
+
703
+ ### Adding Contexts at Runtime
704
+
705
+ The **Raw ODRL** tab in the editor includes a context management panel that
706
+ lets users add or remove `@context` entries without editing JSON directly.
707
+ Click **Add Context**, enter a prefix (e.g., `dome-op`) and a namespace URI
708
+ (e.g., `https://dome-marketplace.eu/ns/`), and the entry is added to the
709
+ policy's `@context` object.
710
+
711
+ ### Standalone Mode
712
+
713
+ Set the `VITE_ODRL_CONTEXT` environment variable (build-time) or
714
+ `window.__ENV__.ODRL_CONTEXT` (runtime injection in Docker):
715
+
716
+ ```bash
717
+ # .env — build-time override
718
+ VITE_ODRL_CONTEXT='{"odrl":"http://www.w3.org/ns/odrl/2/","dome-op":"https://dome-marketplace.eu/ns/"}'
719
+ ```
720
+
721
+ ```javascript
722
+ // env-config.js — runtime injection (Docker envsubst)
723
+ window.__ENV__ = {
724
+ ODRL_CONTEXT: '{"odrl":"http://www.w3.org/ns/odrl/2/","dome-op":"https://dome-marketplace.eu/ns/"}'
725
+ };
726
+ ```
727
+
728
+ ### Embedded Mode
729
+
730
+ Pass the context via the `policy-context` HTML attribute or the
731
+ `policyContext` JavaScript property:
732
+
733
+ ```html
734
+ <!-- HTML attribute (JSON string) -->
735
+ <odrl-policy-editor
736
+ policy-context='{"odrl":"http://www.w3.org/ns/odrl/2/","dome-op":"https://dome-marketplace.eu/ns/"}'
737
+ ></odrl-policy-editor>
738
+ ```
739
+
740
+ ```javascript
741
+ // JavaScript property (object — takes precedence over the attribute)
742
+ const editor = document.querySelector('odrl-policy-editor');
743
+ editor.policyContext = {
744
+ odrl: 'http://www.w3.org/ns/odrl/2/',
745
+ 'dome-op': 'https://dome-marketplace.eu/ns/',
746
+ };
747
+ ```
748
+
749
+ ---
750
+
751
+ ## Testing
752
+
753
+ The project uses [Vitest](https://vitest.dev/) with React Testing Library and
754
+ [MSW](https://mswjs.io/) (Mock Service Worker) for API mocking.
755
+
756
+ ```bash
757
+ # Run all tests once
758
+ npm test
759
+
760
+ # Run tests in watch mode (re-runs on file changes)
761
+ npm run test:watch
762
+
763
+ # Run tests with code coverage report
764
+ npm run test:coverage
765
+
766
+ # Run tests with verbose output (useful in CI)
767
+ npm run test:ci
768
+ ```
769
+
770
+ ---
771
+
772
+ ## Regenerating the API Client
773
+
774
+ If you make changes to the `api/odrl.yaml` OpenAPI spec, regenerate the
775
+ TypeScript API client:
776
+
777
+ ```bash
778
+ npm run generate-api
779
+ ```
780
+
781
+ The generated code lives in `src/api/` and should be committed to the
782
+ repository.