cedar-embeddable-editor 2.0.18 → 2.0.20

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.20] - 2026-10-05
+
+Aligns with `cedar-model-typescript-library@1.0.16`.
+
+- Includes paragraph character limits, every stored constraint problem stated at its field in each language, checked host value shapes, read-only guards and immediate lookup cancellation.
+
+## [2.0.19] - 2026-10-02
+
+Aligns with `cedar-model-typescript-library@1.0.15`.
+
+- Includes `reveal` for taking the user to a field, data quality problems located by the entries that hold them, and stored problems shown at their fields.
+
 ## [2.0.18] - 2026-09-26
 
 Aligns with `cedar-model-typescript-library@1.0.15`.
@@ -21,6 +33,17 @@ Aligns with `cedar-model-typescript-library@1.0.13`.
 
 ### Added
 
+- `reveal(location, options)` on `cedar-embeddable-editor`, which takes the user to a field or
+  element: it turns to the field's page, moves each repeating field or element above it to the
+  named entry, opens the panels around it, scrolls it into view and focuses its control.
+  `{ focus: false }` scrolls without taking focus. It resolves to whether the field could be
+  shown, and changes nothing when it cannot. A problem from the data quality report is itself a
+  location, so a host listing the problems can pass each one straight to `reveal`.
+- `occurrences` on each data quality problem: the entry of each repeating field or element along
+  its path, outermost first. A path alone names one place per entry of everything above it, so a
+  host could not say which entry held a bad value. The same bad value in two entries is now two
+  problems.
+
 - A second element, `cedar-embeddable-field`, registered by the same bundle. It renders one field's
   control and nothing of the form around it, for a host that holds a field artifact rather
   than a template — a designer collecting a default value, above all. The value goes in and
@@ -44,6 +67,18 @@ Aligns with `cedar-model-typescript-library@1.0.13`.
 
 ### Changed
 
+- A field shows what is wrong with a value loaded from a stored instance as soon as the form opens.
+  The error states waited for the control to be edited or touched, so a field the data quality
+  report listed as invalid showed nothing. An empty required field still waits, until the user
+  edits it or is taken to it with `reveal`.
+- The data quality report states at the field the problems no control can find: a stored choice
+  that is not one of the options, a term missing its label or its IRI, an authority identifier
+  that is not a valid IRI, and a list longer than its `maxItems`. A list shorter than its
+  `minItems` is stated once the user is taken to it.
+- The data quality report no longer reports `missingProperty`. It described a repeating field or
+  element absent from the instance CEE read, which CEE writes out as an empty list, so it warned
+  about a defect that saving removed and that no field could show.
+
 - A numeric field's type constraint and a temporal field's errors follow the configured
   language. The numeric sentence was English written into the validator, and the temporal
   widget printed the data quality report's diagnostics, such as `Granularity is year, but the
@@ -83,8 +118,20 @@ Aligns with `cedar-model-typescript-library@1.0.13`.
 - Compact YAML downloads retain the template's root ID but omit the IDs of nested fields and
   elements. Full YAML downloads continue to carry the complete identity tree.
 
+- The form's header sets CEE's name and version stamp beside the mark rather than beneath it, so
+  the identity is no taller than the mark. Beside a title with a description, the identity and the
+  template's version and status keep to the top of the row, level with the title. At 520px or
+  narrower they take a row of their own above the title, which then has the full width.
+
+- Every text box carries `autocomplete="off"`. A browser otherwise listed beneath a field what had
+  been typed into any box with the same name or id, and Angular Material gives each input an id
+  such as `mat-input-3`, so the list could hold values from an unrelated form.
+
 ### Fixed
 
+- `minItems` and `maxItems` on a repeating field inside a repeating element are checked in
+  every entry of the element. They were checked in the entry on screen, so the report changed
+  with the page the user had moved to.
 - Reassigning `cedar-embeddable-field.fieldObject` recreates the control even when the field type
   stays the same, so validators and other initialized settings follow the new artifact.
 - `cedar-embeddable-field` emits `valueChange` when validity changes even if the normalized value

package/README.md

@@ -39,9 +39,9 @@ gives the input properties, the output properties, and the change event a host
 reads.
 
 For the design rationale, the architecture, and deployments in research
-platforms, see [*Author Once, Publish Everywhere: Portable Metadata Authoring
-with the CEDAR Embeddable Editor*](https://doi.org/10.5334/dsj-2026-002),
-published in the *Data Science Journal* (2026).
+platforms, see [_Author Once, Publish Everywhere: Portable Metadata Authoring
+with the CEDAR Embeddable Editor_](https://doi.org/10.5334/dsj-2026-002),
+published in the _Data Science Journal_ (2026).
 
 ## Installing
 
@@ -124,13 +124,57 @@ takes the same page apart step by step, and
 [Embedding in a Framework](https://metadatacenter.readthedocs.io/en/latest/cedar-embeddable-editor/frameworks/)
 covers Angular, React, and Ember.
 
+A dialog host can set `previewMode: true` in either read-only or editable mode
+to omit CEE's identity header and use compact, content-sized form spacing. Template
+descriptions and page navigation remain available. `readOnlyMode` independently
+controls whether values can be edited. Ordinary embeds retain their existing layout.
+
+Trial hosts such as Workspace “Try out” and CED’s editable preview set
+`suppressEmptyFieldErrors: true`. Clearing a control then hides its error state and
+messages even after blur. Nonempty invalid values and incomplete temporal values still
+show errors. This affects presentation only: required fields remain invalid in the quality
+report. Ordinary metadata editing leaves the option off.
+
+## Validation
+
+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
+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.
+Terminology membership and server-side validation remain the host's responsibility.
+
 ## Embedding a Single Field
 
-The bundle registers a second element. `<cedar-embeddable-field>` renders one field's
-control — the same control the editor renders for that field, from the same component
-— and nothing of the form around it: no label, no description, no card. A host that
-holds a field artifact rather than a template puts this where the control belongs and
-draws the rest itself.
+The bundle registers a second element. `<cedar-embeddable-field>` renders one field
+from its artifact. In editable mode it supplies the same bare control CEE uses,
+so a host such as CED can place it in its own form.
+
+With `config = { readOnlyMode: true }`, CEF owns the full presentation: label,
+field type, description, constraints, choices, sources and declared defaults where
+present. The type is named by the icon beside the label. A supplied value is shown
+read-only. CEE uses the same field presentation, so preview hosts only need to supply
+the artifact and their dialog shell.
+
+Set `previewMode: true` with `readOnlyMode: true` when the host supplies the field name
+in its own header. CEF then omits its header, and with it the type icon, while
+retaining the description and value or specification. A host whose header leaves out
+the type, such as the Workspace's preview, also sets `showFieldType: true`.
+CEF then states the type above the description, with the icon its header would have
+drawn (for example, `Paragraph`). A host whose header already shows the type, as CED's
+field cards do, leaves it unset.
+
+Read-only controls have no placeholder text, and fields without constraints draw empty
+boxes. Static fields show their content. A standalone page break is described without
+creating pagination.
 
 Designing a template is what this is for. An author giving a field a default value
 needs somewhere to type it, and the box that collects one has to be the control the
@@ -192,6 +236,20 @@ field?.addEventListener('valueChange', (event: CustomEvent<CedarEmbeddableFieldC
 the control afresh — the field being designed changes type under its author's hand.
 `config` takes one assignment, as the editor's does. A value of a kind the field
 cannot hold is reported through `eventHandler` and ignored rather than coerced.
+Malformed runtime payloads are also rejected, including assignments made before the
+field arrives. Accepted values and artifacts are copied; host mutation after an
+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:
+`9007199254740993` and `0.1234567890123456789` retain every digit. Both forms may be
+assigned back through `value`. Constraint validity remains a separate result.
+
+Read-only mode guards user mutations in the controller, including late callbacks
+and structural edits. Explicit host `value` assignments still work. Controlled-term
+and external-authority searches cancel on a new query, a read-only transition, or
+widget destruction; an old response cannot overwrite a newer query.
 
 Requiredness and cardinality belong to a field's deployment inside a template, and
 this element deploys nothing, so the value it acquires is single and is allowed to be
@@ -385,3 +443,12 @@ for all available settings.
 
 3. In your browser, navigate to `http://localhost:4400/`. The app will
    automatically reload if you change any of the source files.
+
+The host lifecycle matrix in
+`src/app/modules/shared/components/wrapper-lifecycle-matrix.spec.ts` crosses three input
+arrival orders, host mutation, one or two simultaneous numeric/lookup wrapper pairs,
+ordinary/large-integer/precise-decimal values, initial/late/no read-only state,
+and superseded lookup success/error/completion (324 cases). It runs in `npm test`
+with real wrappers, artifact coordination, controllers and lookup streams; rendering
+and HTTP are substituted. The Angular coordinator suite separately verifies rendered
+controls, simultaneous wrappers, host events and malformed assignments.

package/bundle-manifest.host-fonts.json

@@ -4,6 +4,6 @@
     "main.js",
     "polyfills.js"
   ],
-  "bytes": 2182095,
-  "sha256": "b37efb9f7c3e893b74d2a4a7eaf784fcbd7b0b54586f25a93f6c8d7c596ad73c"
+  "bytes": 2228152,
+  "sha256": "7fdb1fbd1a59b2cdc77e6c6d54716398809d6f3438ebe2c99272fde0e5a38647"
 }

package/bundle-manifest.json

@@ -4,6 +4,6 @@
     "main.js",
     "polyfills.js"
   ],
-  "bytes": 2365905,
-  "sha256": "8e62f446b41da71eaf8c46be9818a78e66639d3b2de7e170de7a06edb991b121"
+  "bytes": 2350430,
+  "sha256": "9cc4c9cb9e669d79bba195fdaaa3df9ea11228d54896783bc00ccd21e542d619"
 }

package/cedar-embeddable-editor.d.ts

@@ -45,6 +45,16 @@ export type CeeConfigKey = keyof CeeConfig;
  */
 export interface CeeConfig {
     showTemplateDescription?: boolean;
+    /** Embedding with a host-provided heading, in either read-only or editable mode. Hides CEE's identity header or CEF's field header; keeps descriptions and controls. */
+    previewMode?: boolean;
+    /**
+     * For a read-only CEF preview whose host heading does not name the field's type. The hidden header
+     * carried the icon that names it, so CEF states the type above the description instead, with that
+     * icon. A host whose own heading already shows the type leaves this unset.
+     */
+    showFieldType?: boolean;
+    /** Keep empty trial fields quiet without changing validity or nonempty-value errors. */
+    suppressEmptyFieldErrors?: boolean;
     /**
      * Renders the form without editing controls.
      *
@@ -147,10 +157,22 @@ 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. */
+    severity: 'warning' | 'error';
     /** Machine-readable code, e.g. `numberType` or `temporalGranularity`. */
     code: string;
     /** Path to the offending value, outermost first. */
     path: string[];
+    /**
+     * The entry taken at each repeating field or element along `path`, outermost first.
+     *
+     * A path names one place per entry of everything above it that repeats, and this
+     * says which entry holds the problem. A problem about a whole list, such as
+     * `minItems`, names the entries above the list and none of its own; a `required`
+     * problem names the containing elements whose requirement is unfilled. Pass the problem to
+     * `reveal` to take the user to it.
+     */
+    occurrences: number[];
     /** The field's property name, which is the last path segment. */
     field: string;
     /** The field's declared `_ui.inputType`, or null where it declares none. */
@@ -160,6 +182,31 @@ export interface CeeValidationProblem {
     /** The value that failed, when there is one. */
     value?: unknown;
 }
+/**
+ * A place on the form: a field or element, in particular entries of what repeats.
+ *
+ * A `CeeValidationProblem` is one, so a host can pass a problem straight to `reveal`.
+ */
+export interface CeeLocation {
+    /** Component path from the template root, as a problem's `path` gives it. */
+    path: string[];
+    /**
+     * The entry to show at each repeating field or element along `path`, outermost first.
+     *
+     * Optional, and may be shorter than the repeating components along the path: those
+     * it does not reach stay on the entry they show.
+     */
+    occurrences?: number[];
+}
+/** What a host may ask of `reveal` beyond showing the field. */
+export interface CeeRevealOptions {
+    /**
+     * Whether to move keyboard focus to the field's control. Defaults to true. A host
+     * keeping focus in its own controls, such as a designer showing the field it has
+     * selected, passes false.
+     */
+    focus?: boolean;
+}
 /**
  * What CEE thinks of the instance currently in the form.
  *
@@ -179,15 +226,15 @@ export interface CeeDataQualityReport {
     /**
      * How many of those the instance fills.
      *
-     * A requirement is met when any occurrence carries a value, so this is
-     * unaffected by which page the form is showing.
+     * A required field needs at least one value in every existing containing element.
+     * This is unaffected by which occurrence the form is showing.
      */
     nonNullRequiredFieldValueCount: number;
     /**
      * Validation problems.
      *
-     * Includes one `required` problem for each unsatisfied required field
-     * declaration, while the two counters retain their existing aggregate view.
+     * Includes a located `required` warning for each containing element with an
+     * unanswered requirement. The two counters count declarations, not occurrences.
      */
     problems: CeeValidationProblem[];
     /** True when every required field is filled and no constraint is violated. */
@@ -313,12 +360,35 @@ export interface CedarEmbeddableEditorElement extends HTMLElement {
      * Replacing one is traced, so a page whose messages stop arriving can see why.
      */
     eventHandler: CeeEventHandler;
-    /** The instance as CEDAR JSON. Read-only. */
+    /**
+     * The instance as CEDAR JSON. Read-only.
+     *
+     * An empty object while the editor holds no artifact. An input it refuses because it is not a
+     * readable CEDAR artifact leaves it holding none, so a host that assigns a template on its own, or a
+     * template and instance together through `templateAndInstanceObject`, reads an empty object straight
+     * after the assignment as a refusal. An instance assigned on its own is held while it waits for a
+     * template, so a template refused after it leaves this holding the instance. The refusal's reason
+     * goes to the event handler's `error`.
+     */
     readonly currentMetadata: CeeJsonObject;
     /** The instance as CEDAR YAML. Read-only. */
     readonly currentMetadataYaml: string;
     /** What CEE thinks of the instance. Read-only. */
     readonly dataQualityReport: CeeDataQualityReport;
+    /**
+     * Take the user to a field or element, and resolve whether it could be shown.
+     *
+     * Turns to the field's page, moves each repeating field or element above it to the
+     * named entry, opens the panels around it, scrolls it into view and focuses its
+     * control. A field the user is taken to also states an unanswered requirement, which
+     * a field nobody has reached keeps quiet.
+     *
+     * Resolves false, having changed nothing, for a path the template does not declare,
+     * a hidden field, or an entry that does not exist. A repeating element with no
+     * entries stops the reveal at the element, since nothing inside it is on the form.
+     * Available once the element is in the document and has a template.
+     */
+    readonly reveal: (location: CeeLocation, options?: CeeRevealOptions) => Promise<boolean>;
 }
 /**
  * What one field holds, in the terms its own type is written in.
@@ -331,7 +401,7 @@ export interface CedarEmbeddableEditorElement extends HTMLElement {
  * Embeddable Designer's single `defaultValue: string` has.
  *
  * `none` is an unfilled field. It is also what a numeric field reports while it holds
- * something that is not yet a number, `3.` on the way to `3.5`; `valid` on the change
+ * something that is not yet a number, `-` on the way to `-3.5`; `valid` on the change
  * detail separates that from empty.
  */
 export type CedarEmbeddableFieldValue = {
@@ -342,10 +412,10 @@ export type CedarEmbeddableFieldValue = {
     kind: 'literal';
     value: string;
 }
-/** A numeric field, once what it holds is a finite number. */
+/** A numeric field. Exact decimal strings preserve values a JavaScript number would round. */
  | {
     kind: 'number';
-    value: number;
+    value: number | string;
 }
 /** A date or time, as the ISO literal its granularity calls for. */
  | {
@@ -380,28 +450,26 @@ export interface CedarEmbeddableFieldChangeDetail {
  *
  * The subset of `CeeConfig` that describes a field rather than the form around one.
  * The keys left out — the download menu, the expand controls, the template
- * description — settle what an editor draws around its fields, and this element draws
- * nothing around its own.
+ * description — settle what an editor draws around a whole form. Field labels and
+ * descriptions belong to this element in read-only mode.
  */
-export type CedarEmbeddableFieldConfig = Pick<CeeConfig, 'readOnlyMode' | 'trustTemplateRichText' | 'terminologyBaseUrl' | 'bridgeBaseUrl' | 'defaultLanguage' | 'fallbackLanguage' | 'languageMapPathPrefix'>;
+export type CedarEmbeddableFieldConfig = Pick<CeeConfig, 'readOnlyMode' | 'previewMode' | 'showFieldType' | 'suppressEmptyFieldErrors' | 'trustTemplateRichText' | 'terminologyBaseUrl' | 'bridgeBaseUrl' | 'defaultLanguage' | 'fallbackLanguage' | 'languageMapPathPrefix'>;
 /**
  * One field's control, as a host sees it.
  *
- * Registered as `cedar-embeddable-field`. It renders exactly the widget the editor
- * renders for that field — the same component, not a second implementation — and
- * reports what the widget holds. Around it there is nothing: no label, no description,
- * no card. A host that has a field artifact and wants a value for it draws its own
- * surroundings and puts this where the control goes.
+ * Registered as `cedar-embeddable-field`. Editable, it renders the same bare value
+ * control as CEE, for a host that supplies its own surrounding form.
  *
- * Read-only is the presentation half of the same element. Editable, the field is a
- * control to fill in; read-only with nothing in it, the widget is replaced by a
- * statement of what the field will accept, which is what the editor shows when it
- * renders a template nobody has filled in yet.
+ * Read-only, it owns the complete field presentation shared with CEE: label, type,
+ * description and applicable constraints, choices, sources and defaults. A supplied
+ * value remains visible and cannot be edited. Static content is also described;
+ * a standalone page break has a label and type but does not create pagination.
  *
- * A field artifact carries no requiredness and no cardinality — both belong to a
- * field's deployment in a template, and this element deploys nothing — so the value
- * it acquires is single and is allowed to be absent. That is what makes it usable for
- * a default value, which is optional by definition.
+ * Cardinality belongs to a field's deployment in a template, and this element deploys
+ * nothing, so the value it acquires is single. Requiredness is the field's own: an
+ * artifact that states `requiredValue: true` has an empty value reported as missing,
+ * unless the host sets `suppressEmptyFieldErrors`. CED writes a field on its own with
+ * `requiredValue: false`, which is what leaves a default value free to be empty.
  */
 export interface CedarEmbeddableFieldElement extends HTMLElement {
     /** Typed value event; the inherited overloads still handle every other DOM event. */