cedar-embeddable-editor 2.0.9 → 2.0.10

package/CHANGELOG.md

@@ -7,8 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- 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
+  out as a discriminated union rather than as text: a literal, a number, an ISO temporal
+  literal, an IRI with a label, a list of literals, or an attribute-value field's named
+  slots. `readOnlyMode` presents rather than acquires, replacing an empty control with a
+  statement of what the field will accept. `fieldObject` takes a field artifact rather than a
+  field model, because the element and its host hold separate copies of the model library and
+  CEE reads an artifact through class identity. The bundle grows by 15,474 gzip bytes, to
+  656,506 of the 840,000 the size gate allows.
+
 ### Changed
 
+- Every field CEE renders now goes through one component. The eighteen-way widget switch and
+  the read-only choice between a control and a statement of the field's specification moved
+  out of the component renderer into `CedarFieldWidgetComponent`, which the renderer and the
+  new element both draw. A widget added or rerouted reaches both, and the element cannot
+  drift from the editor the way a second implementation would.
+
+- The three settings the widgets themselves read — the authority endpoints, whether template
+  rich text is trusted, and read-only mode — are applied by one coordinator that both elements
+  use, rather than by the editor alone.
+
 - The download menu names each entry by the artifact it produces, then the serialization:
   `Template - YAML`, `Template - Compact YAML`, `Template - JSON Schema`, `Instance - YAML`,
   `Instance - Compact YAML`, `Instance - JSON-LD`. It lists the three template downloads before the
@@ -17,6 +40,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
 
+### Fixed
+
+- 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
+  does not, including numeric edits such as `1.5` to `1.50` and back.
+
+## [2.0.10] - 2026-09-10
+
+This release aligns CEE's build-time model dependency with the public
+`cedar-model-typescript-library@1.0.8` package. The model library remains compiled into CEE's
+browser bundle and is not a runtime dependency for embedding applications.
+
+### Changed
+
+- The application and visual-test dependency graphs now pin the same public
+  `cedar-model-typescript-library@1.0.8` tarball from npmjs.
+
 ## [2.0.9] - 2026-09-08
 
 This release carries the same shipped code as 2.0.8 against the same public

package/README.md

@@ -103,6 +103,84 @@ 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.
 
+## 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.
+
+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
+field will actually have: a date picker for a date, a term lookup for a controlled
+term, a bounded number box for a number.
+
+```html
+<cedar-embeddable-field></cedar-embeddable-field>
+
+<script src="/assets/cedar-embeddable-editor.js"></script>
+<script type="module">
+  const artifact = await (await fetch('/assets/organism-field.json')).json();
+
+  await customElements.whenDefined('cedar-embeddable-field');
+  const field = document.querySelector('cedar-embeddable-field');
+
+  field.config = { terminologyBaseUrl: 'https://terminology.metadatacenter.org/' };
+  field.addEventListener('valueChange', (event) => console.log(event.detail.value));
+
+  field.fieldObject = artifact;
+</script>
+```
+
+A field artifact, not a field model. A host holding a `TemplateField` from the CEDAR
+Model TypeScript Library — a designer that just built one, say — writes it out and
+assigns the result rather than assigning the object.
+
+Assigning the object costs nothing and looks as though it should work, which is why
+this is worth stating. The element's copy of the model library sits inside the CEE
+bundle and the host's sits inside its own, so the two hold different classes, and CEE
+decides what a field is by identity: `field.cedarFieldType === CedarFieldType.TEXT`,
+and `instanceof` in three dozen other places. Every one of those comparisons is false
+for an instance built elsewhere, so the field renders as a default rather than
+failing. A serialization also survives the two packages pinning different versions of
+the model library, which shared objects would not. The editor's `templateObject`
+takes an artifact for the same reason.
+
+The value comes back as a discriminated union rather than as text, because the
+distinctions are real ones a host has to make again the moment it writes the value
+into an artifact: a number is a number, a term is an IRI with a label, and a checkbox
+group holds a set.
+
+```typescript
+import type { CedarEmbeddableFieldChangeDetail, CedarEmbeddableFieldValue } from 'cedar-embeddable-editor';
+
+declare function recordDefault(value: CedarEmbeddableFieldValue): void;
+
+const field = document.querySelector('cedar-embeddable-field');
+
+field?.addEventListener('valueChange', (event: CustomEvent<CedarEmbeddableFieldChangeDetail>) => {
+  const { value, valid } = event.detail;
+  if (valid) {
+    recordDefault(value);
+  }
+});
+```
+
+`fieldObject` may be reassigned as often as a host likes, and each assignment builds
+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.
+
+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
+absent. That is what makes it usable for a default, which is optional by definition. A
+field declaring its own default starts out holding it.
+
+`readOnlyMode` is the presentation half of the same element: with a value it shows the
+value, and with none it replaces the control with a statement of what the field will
+accept, which is what the editor shows for a template nobody has filled in.
+
 ## Building the Web Component
 
 One command produces the single file an embedder loads. Do not concatenate named

package/bundle-manifest.json

@@ -4,6 +4,6 @@
     "main.js",
     "polyfills.js"
   ],
-  "bytes": 2205237,
-  "sha256": "e6b0007a5479c2039d96dc85402872a4e5b4ea837f242f0a9bc627a22c46b101"
+  "bytes": 2349062,
+  "sha256": "0e8d94c974d7525816530d9c9fa09a4ad394591c6a4e675f5ee4d326b7722432"
 }

package/cedar-embeddable-editor.d.ts

@@ -276,6 +276,10 @@ export interface CedarEmbeddableEditorElement extends HTMLElement {
     /**
      * The template to render, as a parsed CEDAR artifact.
      *
+     * An artifact, not a model, for the reason given at `cedar-embeddable-field`'s
+     * `fieldObject`: the element and its host hold separate copies of the model library,
+     * 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
@@ -316,8 +320,151 @@ export interface CedarEmbeddableEditorElement extends HTMLElement {
     /** What CEE thinks of the instance. Read-only. */
     readonly dataQualityReport: CeeDataQualityReport;
 }
+/**
+ * What one field holds, in the terms its own type is written in.
+ *
+ * The six shapes a CEDAR field value comes in, kept apart rather than flattened to
+ * text: a number is a number, a term is an IRI with a label beside it, a checkbox
+ * group holds a set, and an attribute-value field holds named slots. A host writing
+ * one of these back into an artifact needs the distinction, and collapsing it here
+ * only means the host parses its own input again — which is the fault the CEDAR
+ * 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
+ * detail separates that from empty.
+ */
+export type CedarEmbeddableFieldValue = {
+    kind: 'none';
+}
+/** Text, paragraph, email, phone, a radio choice, a single-choice list. */
+ | {
+    kind: 'literal';
+    value: string;
+}
+/** A numeric field, once what it holds is a finite number. */
+ | {
+    kind: 'number';
+    value: number;
+}
+/** A date or time, as the ISO literal its granularity calls for. */
+ | {
+    kind: 'temporal';
+    value: string;
+}
+/** A controlled term or an external authority record; a link, whose label is null. */
+ | {
+    kind: 'iri';
+    iri: string;
+    label: string | null;
+}
+/** A checkbox group or a multi-select list. */
+ | {
+    kind: 'literals';
+    values: string[];
+}
+/** An attribute-value field, whose slots are named by whoever fills them in. */
+ | {
+    kind: 'attributes';
+    values: Readonly<Record<string, string | null>>;
+};
+/** Detail carried by the `cedar-embeddable-field` element's `valueChange` event. */
+export interface CedarEmbeddableFieldChangeDetail {
+    /** What the field now holds. */
+    value: CedarEmbeddableFieldValue;
+    /** Whether it satisfies the constraints the field declares. */
+    valid: boolean;
+}
+/**
+ * The configuration `cedar-embeddable-field` accepts.
+ *
+ * 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.
+ */
+export type CedarEmbeddableFieldConfig = Pick<CeeConfig, 'readOnlyMode' | '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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export interface CedarEmbeddableFieldElement extends HTMLElement {
+    /** Typed value event; the inherited overloads still handle every other DOM event. */
+    addEventListener(type: 'valueChange', listener: ((this: CedarEmbeddableFieldElement, event: CustomEvent<CedarEmbeddableFieldChangeDetail>) => unknown) | null, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, event: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: 'valueChange', listener: ((this: CedarEmbeddableFieldElement, event: CustomEvent<CedarEmbeddableFieldChangeDetail>) => unknown) | null, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, event: HTMLElementEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    /**
+     * Configuration. Takes one assignment, as the editor's does.
+     *
+     * The endpoints and the languages are facts about the deployment rather than about
+     * the field, and read-only is what this element *is* rather than a state it moves
+     * through: a host wanting the other mode creates the other element.
+     */
+    config: CedarEmbeddableFieldConfig;
+    /**
+     * The field to render, as a parsed CEDAR field artifact.
+     *
+     * An artifact, not a model. A host holding a `TemplateField` from the CEDAR Model
+     * TypeScript Library — a designer building one is the likely case — writes it out and
+     * assigns the result, rather than assigning the object.
+     *
+     * That is a constraint rather than a preference, and it is worth stating because the
+     * object would appear to work. Passing it costs nothing, but the element's copy of the
+     * model library is inside this bundle and the host's is inside its own, so the two hold
+     * different classes. CEE decides what a field is by identity — `field.cedarFieldType
+     * === CedarFieldType.TEXT`, and `instanceof` in three dozen other places — and every
+     * one of those comparisons is false for an instance built elsewhere. Nothing throws;
+     * the field falls through to a default rendering. A serialization also survives the two
+     * packages pinning different library versions, which class shapes do not.
+     *
+     * Assignable as often as a host likes, and each assignment builds the widget afresh.
+     * Set-once protects answers somebody has been typing, and there are none here: the
+     * field being designed changes type under its author's hand, and a designer that had
+     * to discard and rebuild an element for each change would pay a bootstrap for it.
+     *
+     * A field declaring its own default value starts out holding it, so a host can hand
+     * back what it read and see what it wrote.
+     */
+    fieldObject: CeeJsonObject;
+    /**
+     * What the field should hold, replacing whatever it holds now.
+     *
+     * A value whose kind the field cannot take is reported through the event handler and
+     * ignored, rather than being coerced into the nearest thing that would fit. An
+     * attribute-value field takes none: its slots are named by the control that creates
+     * them. A value assigned before the field is checked when the field arrives.
+     * Accepted assignments survive compatible field replacements; incompatible ones
+     * are discarded and cannot reappear after a later replacement.
+     */
+    value: CedarEmbeddableFieldValue;
+    /** Host callbacks, which may be replaced: the last one assigned receives. */
+    eventHandler: CeeEventHandler;
+    /** What the field holds. Read-only. */
+    readonly currentValue: CedarEmbeddableFieldValue;
+    /** Whether what it holds satisfies the field's constraints. Read-only. */
+    readonly currentValueValid: boolean;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'cedar-embeddable-editor': CedarEmbeddableEditorElement;
+        'cedar-embeddable-field': CedarEmbeddableFieldElement;
     }
 }