cedar-embeddable-editor 2.0.23 → 2.0.25

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.25] - 2026-10-19
+
+Aligns with `cedar-model-typescript-library@1.0.21`.
+
+- Moves to Angular, the CDK and Material 22.2.3, whose patch releases block `data:` and `vbscript:` URLs in the sanitizer and harden the compiler and runtime against prototype pollution, and ships DOMPurify 3.4.17 and n3 2.13.12. Chips keep their previous size, spacing and click area.
+
+## [2.0.24] - 2026-10-18
+
+Aligns with `cedar-model-typescript-library@1.0.20`.
+
+- Keeps exact numeric bounds and values through editing and snapshots, checks pattern constraints in bounded workers without discarding answers, holds identifiers and character limits to the shared text policies, separates warnings that do not block saving from errors that do, recovers drafts including unfinished input, and keeps element identities through save acknowledgements.
+
 ## [2.0.23] - 2026-10-08
 
 Aligns with `cedar-model-typescript-library@1.0.19`.

package/README.md

@@ -119,6 +119,23 @@ Read the record back from `currentMetadata` as CEDAR JSON-LD, or from
 `currentMetadataYaml` as YAML. The CEE neither submits nor stores it. The host
 decides when and where a record is saved.
 
+For recovery across reloads, `captureDraft()` returns a JSON-serializable recovery document
+containing the template, accepted metadata and unfinished field input. This is **not** a
+server-saveable artifact. A host can give it to `restoreDraft(draft)` on a fresh element;
+the method returns `false` without consuming the artifact inputs if the format, version or
+input addresses cannot be restored. Restored input participates in ordinary validation.
+The host owns storage, account and deployment scoping, retention and fresh permission/revision
+checks; restoring a draft grants no write permission. Configure the fresh element normally.
+
+For repository saves, call `captureSave()` immediately before submitting its `metadata`.
+If `needsElementIds` is true, read the stored instance after a successful write and verify
+that its ETag equals the write's returned ETag. Pass that document to the snapshot's
+`acknowledge(stored)` function before permitting another save. This adopts assigned element
+IDs without replacing the form, losing newer edits, or confusing reordered occurrences.
+The returned metadata is the submitted form with its assigned IDs, suitable for the host's
+dirty baseline. If readback or acknowledgement fails, retain the draft and block further
+writes until recovery; retrying with unidentified elements can replace their identities.
+
 [Your First Embedded Editor](https://metadatacenter.readthedocs.io/en/latest/cedar-embeddable-editor/first-editor/)
 takes the same page apart step by step, and
 [Embedding in a Framework](https://metadatacenter.readthedocs.io/en/latest/cedar-embeddable-editor/frameworks/)
@@ -140,16 +157,40 @@ report. Ordinary metadata editing leaves the option off.
 Read `dataQualityReport` for the whole instance, including nested and off-screen
 occurrences. Each problem has a code, `severity` (`warning` or `error`), a field
 `path` and occurrence indices. Pass a field problem to `reveal(problem)` to reach it.
-
-Missing required answers, insufficient occurrences and unnamed attribute rows are
-warnings. Invalid values, malformed incoming data and unfinished edits are errors.
-Either makes `isValid` false; the host decides whether saving is allowed. A required
+Use `displayMessage` for the localized user-facing explanation; `message` retains
+the technical diagnostic for logs or a separate details disclosure. Older component
+bundles may omit `displayMessage`.
+
+Each problem also carries a shared `category` and `blocksSave` decision. Structural defects
+(including malformed typed values and unnamed attributes) block instance saves. Well-formed
+values outside declared constraints and incomplete answers are quality warnings and remain
+saveable. Use `canSave` for the instance save gate and `isValid` for overall quality;
+`structurallyValid` reports the representation separately. A required
 field must be answered in every existing containing element. A repeating field
 needs at least one answer within each such element.
 
 The report includes unfinished date/time and attribute-name edits, and `change`
 fires when metadata **or the report** changes. Invalid imported field IRIs and
 well-shaped numeric, temporal and IRI defaults remain available for correction.
+Patterns run in a bounded worker, with the same no-flags, whole-value semantics as Java validation.
+While a check is running, `dataQualityReport.pendingValidation` is `true`, `isValid` is `false`,
+and no provisional pattern error is displayed. Listen for the composed `validationChange` event
+(the detail is the updated report) to refresh a host save gate without treating completion as an
+instance edit. CEF's `valueChange` detail carries the same optional `pendingValidation` flag
+and announces completion even when the completed result remains invalid. A timeout, resource limit or unavailable worker is a `regexEvaluation` verification finding;
+`canSave` remains false while checks are pending. Worker execution needs
+`worker-src blob:` in the host CSP. There is no synchronous fallback.
+
+Populated controlled terms and external-authority values are checked on load, default seeding
+and edits using the configured services. `semanticChecks` records `passed`, `failed`,
+`notChecked` or `unavailable` for each occurrence. Membership uses the exact IRI and complete
+version-aware constraints. Missing configuration and service failures never count as success;
+those findings affect quality but do not prohibit saving a structurally sound instance.
+
+A template pattern change preserves existing preview answers. If a retained answer fails the new
+pattern, the completed report identifies it; a failed or unfinished check never clears the answer
+or removes its containing section. Replacing or destroying the editor cancels obsolete checks.
+
 Terminology membership and server-side validation remain the host's responsibility.
 
 ## Embedding a Single Field
@@ -242,7 +283,8 @@ assignment does not change the editor. Getters and events return detached values
 
 A numeric value has the shape `{ kind: 'number', value: number | string }`.
 Ordinary numbers remain numbers. When converting to a JavaScript number would lose
-significant digits or exceed its range, CEF returns the exact numeric string instead:
+significant digits, exceed its range, or produce an integer outside its safe range,
+CEF returns the exact numeric string instead:
 `9007199254740993` and `0.1234567890123456789` retain every digit. Both forms may be
 assigned back through `value`. Constraint validity remains a separate result.
 
@@ -275,7 +317,7 @@ npm run build:production
 npm run test:visual:prebuilt
 ```
 
-Use Node 24.19.0, which `.nvmrc`, `package.json` and CI all specify. The build and
+Use Node 24.22.0, which `.nvmrc`, `package.json` and CI all specify. The build and
 tests use that same version, so the distribution is produced by the toolchain
 that exercises it.
 
@@ -359,7 +401,7 @@ The visual suite installs nothing here. It runs inside Playwright's own containe
 which carries the browsers it drives, and installs its dependencies there against a
 named volume — so it needs Docker running and no `playwright install` of its own.
 
-The CEE uses Angular 22.1 and Node 24.19.0. `.nvmrc`, the package `engines` field and
+The CEE uses Angular 22.2 and Node 24.22.0. `.nvmrc`, the package `engines` field and
 CI specify the Node version.
 
 The application bundle and the visual fixture generator each install the model

package/bundle-manifest.host-fonts.json

@@ -4,6 +4,6 @@
     "main.js",
     "polyfills.js"
   ],
-  "bytes": 2237021,
-  "sha256": "ee8739e16f93e420373218a88e437afbce27e769156d31b26100c5028e5c96a3"
+  "bytes": 2296561,
+  "sha256": "320c6fde53d6d8b4a8ef911ed9a312c96276dfcc16934ee01018eceaa214afea"
 }

package/bundle-manifest.json

@@ -4,6 +4,6 @@
     "main.js",
     "polyfills.js"
   ],
-  "bytes": 2359327,
-  "sha256": "97bfdc29582a5fab312ed578123ae3a8a10440c7bcb562f0e1ba263da181cfd3"
+  "bytes": 2418867,
+  "sha256": "0821ebe422cfde9db3c07a96c7e1a80e9edcaafb0774ec4d38b57e9f95f2bc8d"
 }

package/cedar-embeddable-editor.d.ts

@@ -128,10 +128,45 @@ export interface CeeConfig {
     languageMapPathPrefix?: string;
 }
 /** A JSON-serialisable value, as it appears in a CEDAR artifact. */
-export type CeeJsonValue = string | number | boolean | null | CeeJsonObject | CeeJsonValue[];
+/** Exact numeric atoms returned by the model library's raw-source readers. Use its JSON writer for serialization. */
+export interface CeeExactNumber {
+    readonly cedarExactDecimal: true;
+    toString(): string;
+    toJSON(): unknown;
+}
+export type CeeJsonValue = string | number | CeeExactNumber | boolean | null | CeeJsonObject | CeeJsonValue[];
 export interface CeeJsonObject {
     [key: string]: CeeJsonValue;
 }
+/** Recovery data, not a server-saveable artifact. Hosts own storage and access checks. */
+export interface CeeRecoveryDraft {
+    format: 'cedar-cee-draft';
+    version: 1;
+    template: CeeJsonObject;
+    metadata: CeeJsonObject;
+    drafts: Array<{
+        path: Array<string | number>;
+        draft: {
+            code: string;
+            message: string;
+            value: unknown;
+            state: unknown;
+        };
+    }>;
+}
+/** A submitted form and an occurrence-safe acknowledgement of its repository identities. */
+export interface CeeSaveSnapshot {
+    readonly metadata: CeeJsonObject;
+    readonly needsElementIds: boolean;
+    /**
+     * Supply the full stored instance from the exact revision acknowledged by the write.
+     * Copies only element identifiers into surviving submitted occurrences, preserving later
+     * edits and reordering. Returns the submitted metadata with those IDs for a dirty baseline.
+     * Throws without changing the form if the snapshot or identities cannot be reconciled.
+     * One successful acknowledgement per snapshot; no change event or form remount.
+     */
+    readonly acknowledge: (stored: CeeJsonObject) => CeeJsonObject;
+}
 /**
  * A template and an instance of it, supplied together.
  *
@@ -157,12 +192,17 @@ export interface CeeTemplateAndInstance {
  * TypeScript host could not read either without a cast.
  */
 export interface CeeValidationProblem {
-    /** Missing answers are warnings; invalid values and unfinished edits are errors. Both affect isValid. */
+    /** Shared rule category and instance save decision. Optional for older producers. */
+    category?: 'structural' | 'constraint' | 'completeness' | 'verification';
+    blocksSave?: boolean;
+    /** Structural defects are errors; value constraints and incomplete verification are warnings. */
     severity: 'warning' | 'error';
     /** Machine-readable code, e.g. `numberType` or `temporalGranularity`. */
     code: string;
     /** Path to the offending value, outermost first. */
     path: string[];
+    /** Exact RFC 6901 location, including atom properties, when available. */
+    location?: string;
     /**
      * The entry taken at each repeating field or element along `path`, outermost first.
      *
@@ -177,8 +217,10 @@ export interface CeeValidationProblem {
     field: string;
     /** The field's declared `_ui.inputType`, or null where it declares none. */
     inputType: string | null;
-    /** Human-readable explanation. */
+    /** Technical diagnostic, retained in English for troubleshooting. */
     message: string;
+    /** Localized user-facing explanation. `message` retains the technical diagnostic. */
+    displayMessage?: string;
     /** The value that failed, when there is one. */
     value?: unknown;
 }
@@ -210,11 +252,23 @@ export interface CeeRevealOptions {
 /**
  * What CEE thinks of the instance currently in the form.
  *
- * Read through `dataQualityReport`. These four members are the whole object: it
- * carried three of CEE's internal working views as well, and the interface was a
- * subset of what a host actually received.
+ * Read through `dataQualityReport`. The report contains validation facts and
+ * counts, without CEE's internal model or working views.
  */
 export interface CeeDataQualityReport {
+    /** Separate structural/save facts from overall answer quality. */
+    structurallyValid?: boolean;
+    canSave?: boolean;
+    semanticChecks?: Array<{
+        path: string[];
+        occurrences: number[];
+        iri: string;
+        status: 'passed' | 'failed' | 'notChecked' | 'unavailable';
+        code: string;
+        message: string;
+    }>;
+    /** Worker validation is unresolved; isValid remains false until it settles. */
+    pendingValidation?: boolean;
     /**
      * How many required fields the template declares.
      *
@@ -237,7 +291,7 @@ export interface CeeDataQualityReport {
      * unanswered requirement. The two counters count declarations, not occurrences.
      */
     problems: CeeValidationProblem[];
-    /** True when every required field is filled and no constraint is violated. */
+    /** True when required answers, local constraints and applicable semantic checks all pass. */
     isValid: boolean;
 }
 /** The model operation that produced a host-visible instance change. */
@@ -310,6 +364,9 @@ export interface CeeEventHandler {
  * handler and meaningless for the three read-only getters below.
  */
 export interface CedarEmbeddableEditorElement extends HTMLElement {
+    /** Validity changed after asynchronous checks; the instance itself did not change. */
+    addEventListener(type: 'validationChange', listener: ((this: CedarEmbeddableEditorElement, event: CustomEvent<CeeDataQualityReport>) => unknown) | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: 'validationChange', listener: ((this: CedarEmbeddableEditorElement, event: CustomEvent<CeeDataQualityReport>) => unknown) | null, options?: boolean | EventListenerOptions): void;
     /** Typed host mutation event; the inherited overloads still handle every other DOM event. */
     addEventListener(type: 'change', listener: ((this: CedarEmbeddableEditorElement, event: CustomEvent<CeeChangeDetail>) => unknown) | null, options?: boolean | AddEventListenerOptions): void;
     addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, event: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
@@ -328,10 +385,13 @@ export interface CedarEmbeddableEditorElement extends HTMLElement {
      * and CEE reads a template through class identity.
      *
      * Assignable more than once while no instance has been supplied: each one replaces the
-     * form, building a fresh context, so nothing of the previous template survives. Once an
-     * instance is loaded the template is fixed, and a further assignment is reported and
-     * ignored — the answers in front of a person were recorded against the template that
-     * would be taken away.
+     * form, building a fresh context. When the new template keeps the previous one's `@id`,
+     * so that it is an edit of it, the new form keeps as much of what the reader entered as
+     * it will take without showing an error, and drops the rest silently. Each pager stays
+     * on the entry the reader was looking at. A template with another `@id` starts the
+     * reader on an empty form. Once an instance is loaded the
+     * template is fixed, and a further assignment is reported and ignored — the answers in
+     * front of a person were recorded against the template that would be taken away.
      */
     templateObject: CeeJsonObject;
     /**
@@ -371,6 +431,12 @@ export interface CedarEmbeddableEditorElement extends HTMLElement {
      * goes to the event handler's `error`.
      */
     readonly currentMetadata: CeeJsonObject;
+    /** Capture immediately before saving. Null while no readable form is loaded. */
+    readonly captureSave: () => CeeSaveSnapshot | null;
+    /** Captures accepted values and unfinished input, independently of validity. */
+    readonly captureDraft: () => CeeRecoveryDraft | null;
+    /** Restore into a fresh element; rejects incompatible or malformed data atomically. */
+    readonly restoreDraft: (draft: CeeRecoveryDraft) => boolean;
     /** The instance as CEDAR YAML. Read-only. */
     readonly currentMetadataYaml: string;
     /** What CEE thinks of the instance. Read-only. */
@@ -440,6 +506,13 @@ export type CedarEmbeddableFieldValue = {
 };
 /** Detail carried by the `cedar-embeddable-field` element's `valueChange` event. */
 export interface CedarEmbeddableFieldChangeDetail {
+    /** Local structure and semantic coverage, separate from default-value validity. */
+    structurallyValid?: boolean;
+    semanticChecks?: CeeDataQualityReport['semanticChecks'];
+    /** Validation facts accompanying a semantic check, for default-value consumers. */
+    problems?: CeeValidationProblem[];
+    /** Present while bounded pattern checks are unresolved; valid stays false. */
+    pendingValidation?: boolean;
     /** What the field now holds. */
     value: CedarEmbeddableFieldValue;
     /** Whether it satisfies the constraints the field declares. */