@seamware/odrl-policy-editor 1.8.0 → 1.8.1-PRE-68.49

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 CHANGED
@@ -335,6 +335,14 @@ at runtime triggers a re-render automatically.
335
335
  | `hide-raw-tab` | Boolean — hides the raw ODRL JSON editor tab | absent (visible) |
336
336
  | `hide-template-tab` | Boolean — hides the template selection tab | absent (visible) |
337
337
  | `hide-template-create-tab` | Boolean — hides the template management tab (create/edit/delete templates) | absent (visible) |
338
+ | `summary` | `"side"` \| `"tab"` \| `"none"` — where the live policy summary is shown | `"side"` |
339
+ | `hide-cancel-button` | Boolean — hides the Cancel button (e.g. when the host provides its own) | absent (visible) |
340
+ | `variant` | `"card"` \| `"plain"` — editor framed as a card, or with no chrome | `"card"` |
341
+ | `load` | `"remote"` \| `"none"` — fetch the policy when `mode="edit"` | `"remote"` |
342
+ | `save` | `"remote"` \| `"none"` — store the policy in the PAP; `none` removes the Save button | `"remote"` |
343
+ | `validate` | `"remote"` \| `"none"` — validate against the PAP; `none` removes the Validate button and panel | `"remote"` |
344
+ | `templates` | `"remote"` \| `"none"` — list and manage PAP templates; `none` removes both template tabs | `"remote"` |
345
+ | `mappings` | `"remote"` \| `"none"` — fetch the visual builder's dropdown mappings | `"remote"` |
338
346
 
339
347
  Boolean attributes follow the HTML convention: their **presence** means `true`
340
348
  (the tab is hidden) and their **absence** means `false` (the tab is visible).
@@ -358,6 +366,94 @@ editor.setAttribute('locale', 'de');
358
366
  editor.setAttribute('api-base-url', 'https://new-api.example.com');
359
367
  ```
360
368
 
369
+ #### Look: variant and theme tokens
370
+
371
+ By default the editor is drawn as a card (background, border, radius, shadow
372
+ and padding). `variant="plain"` removes that frame, for hosts that already
373
+ put it inside a card or a modal.
374
+
375
+ Tabs, buttons, cards and the step badges follow the `--odrl-*` theme tokens
376
+ instead of Bootstrap's own colors, so setting tokens restyles them: the tabs
377
+ are an underlined strip in the primary color, primary buttons are filled with
378
+ it, secondary and info buttons are outlined, and danger and success buttons use
379
+ their tokens. Besides the existing tokens there are two new ones:
380
+
381
+ | Token | Meaning |
382
+ |-------|---------|
383
+ | `odrl-primary-text-color` | Text on a primary-colored fill (primary buttons, step badges) |
384
+ | `odrl-card-radius` | Border radius of cards, the outer one and the step cards |
385
+ | `odrl-input-bg` | Background of text fields, selects and checkboxes |
386
+
387
+ The light and dark presets are plain CSS on the host (`theme="light"` /
388
+ `theme="dark"`), so a page can override any token with a normal rule instead
389
+ of `themeConfig`; no JavaScript needed, and it keeps following the page's own
390
+ theme:
391
+
392
+ ```css
393
+ odrl-policy-editor {
394
+ --odrl-primary-color: var(--my-brand-color);
395
+ --odrl-card-radius: 1rem;
396
+ }
397
+ ```
398
+
399
+ `themeConfig` still works and wins over both.
400
+
401
+ Set them with the `themeConfig` property:
402
+
403
+ ```javascript
404
+ editor.themeConfig = {
405
+ 'odrl-primary-color': '#1a3461',
406
+ 'odrl-primary-text-color': '#ffffff',
407
+ 'odrl-card-radius': '1rem',
408
+ };
409
+ ```
410
+
411
+ #### Layout: summary and Cancel
412
+
413
+ The live policy summary sits in a column beside the visual builder, which only
414
+ makes sense on wide screens (the breakpoint follows the viewport, not the
415
+ space the editor actually has, so it also misfires inside a narrow modal or
416
+ panel). `summary="tab"` moves it to its own **Summary** tab and gives the
417
+ builder the full width; `summary="none"` removes it.
418
+
419
+ `hide-cancel-button` hides the Cancel button, for hosts that already provide
420
+ their own (a modal's footer, say). With `save` and `validate` also `none`, no
421
+ action row is rendered at all.
422
+
423
+ The editor renders inside a Shadow DOM, but its sticky summary used
424
+ `z-index: 1020`, which competed with the host page's own stacking contexts.
425
+ The element now isolates its stacking context, so nothing inside it can paint
426
+ over the host page.
427
+
428
+ #### Backend capabilities
429
+
430
+ `load`, `save`, `validate`, `templates` and `mappings` decide, one by one,
431
+ whether the editor talks to the PAP. Each defaults to `remote` (the behaviour
432
+ of earlier versions); `none` makes no request and hides the UI that depends on
433
+ it. Unknown values fall back to `remote`.
434
+
435
+ Used as a form control — the host owns the policy and nothing goes to the PAP:
436
+
437
+ ```html
438
+ <odrl-policy-editor
439
+ load="none" save="none" validate="none" templates="none" mappings="none"
440
+ ></odrl-policy-editor>
441
+ ```
442
+
443
+ ```javascript
444
+ editor.policy = existingPolicy; // object or JSON text
445
+ editor.mappings = { actions: [...], operators: [...], leftOperands: [...] };
446
+ editor.addEventListener('policy-changed', (e) => store(e.detail.policy));
447
+ ```
448
+
449
+ With `mappings="none"` the visual builder offers the mappings the PAP ships
450
+ with (generated from the backend's `mapping.json` at build time, so they match
451
+ the PAP of the same release). Set the `mappings` property to extend or override
452
+ them: its entries are layered over the built-in ones per attribute, and an
453
+ entry with the same `name` replaces the built-in one. Mappings an operator adds
454
+ through the PAP's `paths.mapping` are only visible with `mappings="remote"`. With `save="none"`,
455
+ filling in a template loads the result into the editor instead of storing it.
456
+
361
457
  ### JavaScript Properties
362
458
 
363
459
  For richer configuration that cannot be expressed as string attributes, use
@@ -370,6 +466,8 @@ JavaScript properties on the element:
370
466
  | `fieldTemplate` | `FieldTemplate` | Pre-fills the builder form and optionally locks fields (client-side; distinct from stored templates) |
371
467
  | `policyContext` | `Record<string, string>` | Default `@context` for new policies (takes precedence over attribute) |
372
468
  | `serviceId` | `string` | Service scope for policy/template operations (takes precedence over attribute) |
469
+ | `policy` | `object \| string` | The working policy (object or JSON text); reads back the latest edit |
470
+ | `mappings` | `Mappings` | Builder dropdown mappings; when set, `/mappings` is not fetched. Layered over the PAP's built-in mappings (same `name` wins); with `mappings="none"` the built-ins are used as they are |
373
471
 
374
472
  ```javascript
375
473
  const editor = document.querySelector('odrl-policy-editor');
@@ -419,6 +517,7 @@ Events bubble and cross Shadow DOM boundaries (`composed: true`).
419
517
  | `editor-cancelled` | `{}` | The user clicks Cancel |
420
518
  | `template-created` | `{ template: object, id: string }` | A new template is created in the management tab |
421
519
  | `template-updated` | `{ template: object, id: string }` | An existing template is updated in the management tab |
520
+ | `policy-changed` | `{ policy: OdrlPolicyJson }` | The policy is edited (builder, raw JSON or template); not for the initial or host-set policy |
422
521
 
423
522
  ```javascript
424
523
  const editor = document.querySelector('odrl-policy-editor');
@@ -543,7 +642,9 @@ editor — they will not interfere with the host page's styles.
543
642
 
544
643
  ## Internationalization (i18n)
545
644
 
546
- The frontend ships with English (`en`) as the default and only built-in locale.
645
+ The frontend ships with English (`en`, the default) and Spanish (`es`) as built-in locales;
646
+ set `locale="es"` and the whole UI is translated, no `i18nStrings` needed. Other locales
647
+ fall back to English, plus whatever you override.
547
648
  The i18n system supports runtime locale switching and partial string overrides,
548
649
  making it easy to add new languages without rebuilding.
549
650
 
@@ -18,6 +18,45 @@ export type EditorMode = 'create' | 'edit';
18
18
  /** Theme preset names supported by the embedded component. */
19
19
  export type EmbeddedThemePreset = 'light' | 'dark';
20
20
 
21
+ // ---------------------------------------------------------------------------
22
+ // Capabilities
23
+ // ---------------------------------------------------------------------------
24
+
25
+ /** Operations that can be served by the PAP backend. */
26
+ export type Capability = 'load' | 'save' | 'validate' | 'templates' | 'mappings';
27
+
28
+ /**
29
+ * Where a capability is served from: `"remote"` (the PAP API, the default) or
30
+ * `"none"` (switched off: no request is made and its UI is not rendered).
31
+ */
32
+ export type CapabilityMode = 'remote' | 'none';
33
+
34
+ /** The mode of every capability. */
35
+ export type CapabilityModes = Record<Capability, CapabilityMode>;
36
+
37
+ // ---------------------------------------------------------------------------
38
+ // Layout
39
+ // ---------------------------------------------------------------------------
40
+
41
+ /**
42
+ * Where the live policy summary is shown: `"side"` (a column beside the
43
+ * builder, wide screens only), `"tab"` (its own tab) or `"none"`.
44
+ */
45
+ export type SummaryPlacement = 'side' | 'tab' | 'none';
46
+
47
+ /**
48
+ * How the editor is framed: `"card"` draws it as a card (background, border,
49
+ * radius, shadow, padding); `"plain"` adds no chrome, for hosts that already
50
+ * put it inside a card or a modal.
51
+ */
52
+ export type EditorVariant = 'card' | 'plain';
53
+
54
+ /** Action buttons the host can hide; each, when `true`, hides its button. */
55
+ export interface ButtonVisibility {
56
+ /** When `true`, hides the Cancel button. */
57
+ hideCancelButton: boolean;
58
+ }
59
+
21
60
  // ---------------------------------------------------------------------------
22
61
  // Tab visibility
23
62
  // ---------------------------------------------------------------------------
@@ -55,6 +94,11 @@ export interface TabVisibility {
55
94
  * ```
56
95
  */
57
96
  export interface EmbeddedEventMap {
97
+ /**
98
+ * Fired whenever the policy is edited (builder, raw JSON or template).
99
+ * Not fired for the initial policy or one set through the `policy` property.
100
+ */
101
+ 'policy-changed': { policy: Record<string, unknown> };
58
102
  /**
59
103
  * Fired after a new policy is successfully saved.
60
104
  *
@@ -123,6 +167,14 @@ export interface EmbeddedConfig {
123
167
  * Defaults to all tabs visible.
124
168
  */
125
169
  hiddenTabs: TabVisibility;
170
+ /** Where each backend operation is served from. All `"remote"` by default. */
171
+ capabilities: CapabilityModes;
172
+ /** Where the policy summary is shown. Defaults to `"side"`. */
173
+ summaryPlacement: SummaryPlacement;
174
+ /** Which action buttons are hidden. */
175
+ hiddenButtons: ButtonVisibility;
176
+ /** How the editor is framed. Defaults to `"card"`. */
177
+ variant: EditorVariant;
126
178
  }
127
179
 
128
180
  // ---------------------------------------------------------------------------
@@ -151,6 +203,14 @@ export const TAG_NAME: 'odrl-policy-editor';
151
203
  * | `hide-raw-tab` | Boolean — hides the raw ODRL JSON editor tab | absent |
152
204
  * | `hide-template-tab` | Boolean — hides the template selection tab | absent |
153
205
  * | `hide-template-create-tab` | Boolean — hides the template management tab | absent |
206
+ * | `summary` | `"side"` \| `"tab"` \| `"none"` — where the policy summary is shown | `"side"` |
207
+ * | `hide-cancel-button` | Boolean — hides the Cancel button | absent |
208
+ * | `variant` | `"card"` \| `"plain"` — framed as a card, or no chrome | `"card"` |
209
+ * | `load` | `"remote"` \| `"none"` — fetch the policy when `mode="edit"` | `"remote"` |
210
+ * | `save` | `"remote"` \| `"none"` — store the policy in the PAP (Save button) | `"remote"` |
211
+ * | `validate` | `"remote"` \| `"none"` — validate against the PAP (Validate button) | `"remote"` |
212
+ * | `templates` | `"remote"` \| `"none"` — list and manage PAP templates | `"remote"` |
213
+ * | `mappings` | `"remote"` \| `"none"` — fetch the builder's dropdown mappings | `"remote"` |
154
214
  *
155
215
  * ## JS Properties
156
216
  *
@@ -159,11 +219,14 @@ export const TAG_NAME: 'odrl-policy-editor';
159
219
  * - `fieldTemplate` — a FieldTemplate object to pre-fill and constrain the editor
160
220
  * - `policyContext` — custom JSON-LD `@context` object/string for new policies
161
221
  * - `serviceId` — service ID string for service-scoped policy operations
222
+ * - `policy` — the working policy (object or JSON text); reads back the latest edit
223
+ * - `mappings` — builder dropdown mappings, used instead of fetching them
162
224
  *
163
225
  * ## Custom Events
164
226
  *
165
227
  * | Event | Detail |
166
228
  * |--------------------|---------------------------------------------|
229
+ * | `policy-changed` | `{ policy: object }` |
167
230
  * | `policy-created` | `{ policy: object, id: string }` |
168
231
  * | `policy-updated` | `{ policy: object, id: string }` |
169
232
  * | `policy-validated` | `{ result: object }` |
@@ -243,6 +306,28 @@ export declare class OdrlPolicyEditorElement extends HTMLElement {
243
306
  * ```
244
307
  */
245
308
  serviceId: string | undefined;
309
+
310
+ /**
311
+ * The working policy. Accepts an object or its JSON text; reading it back
312
+ * returns the policy as last edited, so it works as the editor's value.
313
+ * Listen to `policy-changed` to react to edits.
314
+ *
315
+ * @example
316
+ * ```js
317
+ * editor.policy = existingPolicy;
318
+ * editor.addEventListener('policy-changed', (e) => store(e.detail.policy));
319
+ * ```
320
+ */
321
+ policy: Record<string, unknown> | string | undefined;
322
+
323
+ /**
324
+ * Mappings (actions, operators, operands...) the visual builder offers.
325
+ * When set the builder does not fetch them from the PAP; they are layered
326
+ * over the PAP's built-in mappings, and a mapping with the same `name`
327
+ * replaces the built-in one. With `mappings="none"` and nothing set, the
328
+ * built-in mappings are used as they are.
329
+ */
330
+ mappings: Record<string, unknown> | undefined;
246
331
  }
247
332
 
248
333
  // ---------------------------------------------------------------------------