@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 +782 -0
- package/dist-component/odrl-policy-editor.d.ts +185 -0
- package/dist-component/odrl-policy-editor.js +36446 -0
- package/package.json +76 -0
package/README.md
ADDED
|
@@ -0,0 +1,782 @@
|
|
|
1
|
+
# ODRL PAP Frontend
|
|
2
|
+
|
|
3
|
+
[](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.
|