cedar-embeddable-editor 1.5.2 → 2.0.2

package/README.md

@@ -1,342 +1,228 @@
-# Cedar Embeddable Editor (CEE)
+# CEDAR Embeddable Editor (CEE)
 
-The CEDAR Embeddable Editor is as a web component that implements the functionality of the CEDAR Metadata Editor.
+[![Test](https://github.com/metadatacenter/cedar-embeddable-editor/actions/workflows/test.yml/badge.svg?branch=develop)](https://github.com/metadatacenter/cedar-embeddable-editor/actions/workflows/test.yml)
 
-It takes CEDAR JSON Schema templates as input, and produces CEDAR JSON-LD metadata.
+The CEDAR Embeddable Editor (CEE) is a reusable Web Component for adding
+structured, standards-based metadata authoring to web applications.
 
-## Running as a standalone application
+The CEE dynamically renders data-entry forms from machine-actionable CEDAR
+templates and produces semantically rich metadata as JSON-LD. Templates define
+the fields, constraints, controlled vocabularies, and repeatable structures in a
+form, allowing the metadata-authoring experience to evolve independently of the
+application that embeds it. The CEE also supports ontology-backed value selection
+and persistent identifiers from external authorities such as ORCID and ROR.
 
-You can run CEE as a standalone application. This is helpful for developers to see changes to the code reflected immediately in the application. To run CEE in the standalone mode (NOT as a Webcomponent), you will need the editor itself and the sample templates that the editor uses. These are stored in a [separate repo](https://github.com/metadatacenter/cedar-component-distribution).
+For the design rationale, 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).
 
-Proceed with the following steps:
+For embedding and using the CEE in a web application, see the
+[CEDAR Embeddable Editor documentation](https://metadatacenter.readthedocs.io/en/latest/cedar-embeddable-editor/intro/).
 
-### Clone the repository
+This README covers developing, building, and testing the component.
 
-Clone this repository onto a local directory of your choice:
+## Building the Web Component
 
-```shell
-git clone https://github.com/metadatacenter/cedar-embeddable-editor.git
-git clone https://github.com/metadatacenter/cedar-component-distribution.git
-```
+The CEE is shipped as one JavaScript file that can be embedded in an application or
+HTML page. Do not concatenate named Angular output files manually: their names,
+locations, and module structure change when Angular changes builders.
 
-### Edit configuration
+Build the production application, then run the browser suite against the
+single-file bundle it produced:
 
-1. Open the file ```app/app.component.dev.ts``` in your favorite editor.
-2. Edit configuration parameters based on your local environment (see section [Configuration](https://github.com/metadatacenter/cedar-embeddable-editor/tree/develop#configuration) for details).
-
-### Build the project and start the server
-
-1. Navigate to the CEE directory:
 ```shell
-$ cd <...>/<clone directory>/cedar-embeddable-editor/
-```
-1. Run these commands:
-```shell
-cedar-embeddable-editor$ npm install
-cedar-embeddable-editor$ ng serve
+nvm use
+npm run build:production
+npm run test:visual:prebuilt
 ```
 
-1. In a different shell navigate to the component distribution directory:
-```shell
-$ cd <...>/<clone directory>/cedar-component-distribution/
-```
+Use Node 24.19.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.
+
+Once that exact bundle is green, stage the publishable npm directory from it:
 
-1. Run these commands:
 ```shell
-cedar-embeddable-editor$ npm install
-cedar-embeddable-editor$ ng serve
+npm run package:npm:prebuilt
 ```
 
-1. In your browser, navigate to `http://localhost:4400/`. The app will automatically reload if you change any of the source files.
+For a release candidate, `npm run test:package` performs both operations in one command: it builds
+and browser-tests the production bundle, then stages and verifies the package from those exact
+tested bytes.
 
-## Building the Webcomponent
+This copies the tested bytes to
+`dist-npm/cedar-embeddable-editor/cedar-embeddable-editor.js`, refreshes its
+version, README, changelog, and package lock, and records the bundle manifest.
+The command fails if the browser bundle is stale or does not match its SHA-256
+digest. `npm run check:npm-package` can repeat the byte-for-byte verification
+before `npm pack` or `npm publish`.
 
-This method creates a single Javascript (JS) file that encapsulates all the functionality of CEE. The JS file can be embedded in any application or HTML page. To build a CEE Webcomponent, proceed with these steps:
+## Testing
 
-### Build and copy the Webcomponent JS file
+The complete test gate is available from the repository root:
 
-1. Run the build command:
 ```shell
-cedar-embeddable-editor$ ng build --configuration=production
+npm run test:ci
 ```
-1. Combine the generated files into a single file and copy the final JS to the sample application:
-```shell
-cedar-embeddable-editor$ cat dist/cedar-embeddable-editor/{runtime,polyfills,main}.js > cedar-embeddable-editor.js
-```
-
-## Running as an `npm` package
-
-Please import the latest version of the editor into your project from: [https://www.npmjs.com/package/cedar-embeddable-editor](https://www.npmjs.com/package/cedar-embeddable-editor)
 
-## Configuration
+It runs, in order:
 
-### Configuration file
+1. `ng lint` over the sources and the ESLint configuration.
+2. A type check of the application and the domain harness, with `strict` on
+   throughout.
+3. The unit tests, in Node under Vitest.
+4. The headless domain harness with V8 coverage, and its per-directory coverage
+   floors.
+5. A production build, then the Playwright suite against that bundle, in a
+   container: the full Chromium baseline at desktop and narrow viewport sizes,
+   plus focused Chromium, Firefox and WebKit compatibility checks. The container
+   is what makes a screenshot baseline mean the same thing on a laptop and on CI,
+   so the pixel budget is zero — see `visual/run-in-container.sh`.
+6. Staging the npm package from the bundle the suite just exercised, which
+   checks the raw and gzip size budgets and verifies every staged byte against
+   its source.
 
-The CEE configuration file format and storage location depends on the application and the mode in which CEE is being used.
-
-* When running CEE in the standalone mode (developer mode), the configuration parameters are stored in and read from the file: `src/app/app.component.dev.ts`.
-* When running CEE as a generic Webcomponent, the configuration parameters can be stored in any `.json` file that is visible to the application that embeds CEE Webcomponent. CEE Webcomponent API provides a method for loading the configuration file from its path at runtime. For example:
-```javascript
-document.addEventListener('WebComponentsReady', function () {
-  const cee = document.querySelector('cedar-embeddable-editor');
-  cee.loadConfigFromURL('assets/data/cee-config.json');
-});
-```
-* The configuration can also be passed into the editor as a json map. In Angular this looks as follows:
-```html
-<cedar-embeddable-editor
-  [config]="conf"
-  [templateObject]="template"
-  [instanceObject]="instance"
-></cedar-embeddable-editor>
-```
+The domain corpora are checked into `harness/fixtures/`; running the tests does
+not require `cedar-artifact-library` or `cedar-test-artifacts` checkouts.
 
+`.github/workflows/test.yml` runs the same gate on every pull request and on
+pushes to `main` and `develop`. Nothing is published from CI: releasing is a
+separate, manual procedure.
 
-### Required configuration parameters
+### Auditing what ships
 
-* **showSampleTemplateLinks:** Wether the sample links are shown or not.
-  * For production this should be false, the template should be injected into the component by the embedding application
-* **terminologyIntegratedSearchUrl:** The URL of the CEDAR integrated search endpoint that communicates with BioPortal.
-  * The value `https://terminology.metadatacenter.org/bioportal/integrated-search` should work for the majority of applications.
-
-```json
-{
-  "showSampleTemplateLinks": false,
-  "terminologyIntegratedSearchUrl": 'https://terminology.metadatacenter.org/bioportal/integrated-search',
-}
+```shell
+npm run audit:prod
 ```
 
-### Optional configuration parameters
-
-There are other optional configuration parameters available for controlling various aspects of the CEE user interface. Most of these are self-explanatory. The example below includes the default values in cases, where the parameter isn't explicitly declared.
-
-```json
-{
-  "sampleTemplateLocationPrefix": "http://localhost:4240/cedar-embeddable-editor-sample-templates/",
-  "loadSampleTemplateName": "01",
-  "expandedSampleTemplateLinks": true,
-  "showTemplateDescription": false,
-
-  "showTemplateRenderingRepresentation": true,
-  "expandedTemplateRenderingRepresentation": false,
-
-  "showInstanceDataCore": true,
-  "expandedInstanceDataCore": false,
-
-  "showMultiInstanceInfo": true,
-  "expandedMultiInstanceInfo": false,
-
-  "showInstanceDataFull": false,
-  "expandedInstanceDataFull": false,
-
-  "showTemplateSourceData": true,
-  "expandedTemplateSourceData": false,
-
-  "showDataQualityReport": false,
-  "expandedDataQualityReport": false,
-
-  "showHeader": true,
-  "showFooter": true,
-
-  "languageMapPathPrefix": null,
-  "defaultLanguage": "en",
-  "fallbackLanguage": "en",
+Only runtime dependencies reach the file an embedder downloads, so this audit is
+the one that describes the shipped artifact, and it is deliberately not part of
+`test:ci` — it can fail on a disclosure rather than on a commit, which would
+break an unrelated pull request its author cannot fix.
 
-  "collapseStaticComponents": false,
-  "showStaticText": true,
-  
-  "readOnlyMode": false,
-  "hideEmptyFields": false,
-  "showPreferencesMenu": true
-}
-```
-Enabling of hiding empty fields is only possible in read-only mode.
-## Metadata API
-
-CEE Webcomponent includes APIs for exporting metadata externally and importing metadata into CEE.
+A root `npm audit` also reports on development tooling that is not shipped to an
+embedder. **Never run `npm audit fix --force` here:** it can replace the declared
+toolchain with incompatible major versions. Review and update affected
+dependencies explicitly instead.
 
-### Metadata Export
+### First-time setup
 
-The metadata currently being edited inside CEE can be exported at anytime by making this API call:
+The CEE resolves `cedar-model-typescript-library` from npmjs.org, so a sibling
+checkout is not needed:
 
-```javascript
-const meta = cee.currentMetadata;
+```shell
+nvm use
+npm ci
+npm --prefix harness ci
 ```
 
-In the example below, the metadata is sent to an external endpoint every 15 seconds:
-
-```javascript
-document.addEventListener('WebComponentsReady', function () {
-  const cee = document.querySelector('cedar-embeddable-editor');
-  cee.loadConfigFromURL('assets/data/cee-config.json');
-  const saveTime = 15000; // 15 seconds
-
-  setInterval(() => {
-    const meta = cee.currentMetadata;
-
-    const xhr = new XMLHttpRequest();
-    xhr.open("POST", "http://localhost:8001/metadatasave.php");
-    xhr.setRequestHeader("Accept", "application/json");
-    xhr.setRequestHeader("Content-Type", "application/json");
-    xhr.send(JSON.stringify(meta, null, 2));
-    console.log('Saved metadata after ' + saveTime / 1000 + ' seconds');
-  }, saveTime);
-});
-```
+The visual suite installs nothing here. It runs inside Playwright's own container,
+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.
 
-### Template Injection
+The CEE uses Angular 22.1 and Node 24.19.0. `.nvmrc`, the package `engines` field and
+CI specify the Node version.
 
-You can inject your template into CEE:
+The application bundle and the visual fixture generator each install the model
+library directly from npmjs.org:
 
-```javascript
-cee.templateObject = yourCustomTemplateJson;
+```json
+"cedar-model-typescript-library": "<version>"
 ```
 
-### Metadata Injection
+Keep the version in the root and `visual/` manifests, and both lockfiles, in
+sync. The production bundle imports the root copy while the browser fixtures are
+generated with the visual copy, so a mismatch means the tests and the artifact
+are using different model contracts. The harness declares no separate copy; it
+resolves the root installation.
 
-You can inject your metadata into CEE, provided it matches the template currently being edited:
+### Focused test commands
 
-```javascript
-cee.instanceObject = yourCustomMetadataJson
-```
+Use these when working on one layer:
 
-In the example below, the metadata is fetched from a remote URL and injected into CEE:
-
-```javascript
-function restoreMetadataFromURL(metaUrl, cee, successHandler = null, errorHandler = null) {
-  const xhr = new XMLHttpRequest();
-  xhr.onreadystatechange = () => {
-    if (xhr.readyState === XMLHttpRequest.DONE) {
-      if (xhr.status === 200) {
-        const jsonMeta = JSON.parse(xhr.responseText);
-        cee.instanceObject = jsonMeta;
-
-        if (successHandler) {
-          successHandler(jsonMeta);
-        }
-      } else {
-        if (errorHandler) {
-          errorHandler(xhr);
-        }
-      }
-    }
-  };
-  xhr.open('GET', metaUrl, true);
-  xhr.send();
-}
-
-document.addEventListener('WebComponentsReady', function () {
-  const cee = document.querySelector('cedar-embeddable-editor');
-  cee.loadConfigFromURL('assets/data/cee-config.json');
-  restoreMetadataFromURL('uploads/metadata-for-restore.json', cee);
-});
+```shell
+npm run test:unit:ci          # Vitest unit tests, one run
+npm run test:unit:coverage    # unit tests with coverage report
+npm run test:domain           # Vitest domain harness
+npm run test:domain:coverage  # domain harness with coverage report
+npm run test:bundle-size      # exact raw and gzip budgets for the shipped bundle
+npm run test:visual           # production build, fixture preparation, Playwright
 ```
 
-To reiterate, the metadata being injected **MUST** match the template currently being edited and open in your browser window.
+`npm test` runs the unit tests once, and `npm run test:watch` keeps them running
+for interactive development. Use `npm run test:ci` for a complete verification.
 
-### Injecting Template And Metadata Together
+The unit tests run in Node and do not use `TestBed` or Angular's JIT compiler.
+Browser behavior belongs in the Playwright suite under `visual/`, which tests the
+shipped bundle rather than the sources.
 
-You can inject your template and metadata together into CEE:
-
-```javascript
-const templateAndInstance = {templateObject: object, instanceObject: object};
-cee.templateAndInstanceObject = templateAndInstance;
-```
+## Running
 
-Injecting template and metadata together brings performance benefits as well as allows configuring hiding empty fields.
-Object being injected must strictly have two objects one named 'templateObject' and the other 'instanceObject'.
+### As an `npm` package
 
-### Data Quality Report
+Releases are published to npmjs.org as
+[`cedar-embeddable-editor`](https://www.npmjs.com/package/cedar-embeddable-editor)
+under the `latest` tag, so an embedder installs the current one by name:
 
-The dataQualityReport summarizes basic metrics on the instance data.
-
-```javascript
-const report = cee.dataQualityReport;
+```shell
+npm install cedar-embeddable-editor
 ```
 
-At the moment these three fields are available, with more to come:
+The `latest` tag is the public stable channel. To see the current release without
+depending on a version copied into this README:
 
-```
-requiredFieldValueCount: int
-nonNullRequiredFieldValueCount: int
-isValid: boolean
+```shell
+npm view cedar-embeddable-editor version
 ```
 
-### Language Maps / Translations
+### As a standalone application
 
-The application currently has two built-in language maps: `en` and `hu`. If you do not specify any language-related config option, the default `English` map will be used.
-
-If you wish to change the language to another built-in one (currently the only other language is `Hungarian`), specify the config like below:
-
-```json
-{
-  "defaultLanguage": "hu",
-  "fallbackLanguage": "en"
-}
-```
+You can run the CEE as a standalone application. This is helpful for developers to
+see changes to the code reflected immediately in the application.
 
-You can use external language maps as well. In order to do this, specify a relative path to a folder containing the language file. The file should be named `x.json`, and should have the identical structure of the language map found in the source of the application:
+Proceed with the following steps:
 
-https://github.com/metadatacenter/cedar-embeddable-editor/blob/main/src/assets/i18n-cee/en.json
+#### Clone the repository
 
-In order to use an external language file, specify the config as follows:
+Clone this repository onto a local directory of your choice:
 
-```json
-{
-  "languageMapPathPrefix": "/assets/i18n-cee/",
-  "defaultLanguage": "de",
-  "fallbackLanguage": "en"
-}
+```shell
+git clone https://github.com/metadatacenter/cedar-embeddable-editor.git
 ```
 
-In the example above we want to use a `German` language file, which is located in the specified directory. Starting the path with `/` makes the path absolute. 
-
-In our case the `/assets/i18n-cee/de.json` will be loaded if present.
-
-If the file is missing, the `/assets/i18n-cee/en.json` will be used.
-
-If that file is also missing, the built-in `de` map would be the next. As this does not exist at this moment, the last option, the built-in `en` map will be used.
-
-Information about the loading process is logged onto the console with the `CEE TRACE` prefix. 
+#### Edit configuration
 
-### Listening for changes
+Open the standalone application's configuration file, `src/app/app.component.dev.ts`.
+This minimal configuration enables lookups through the public CEDAR services:
 
-If you need to listen to data changes inside the embeddable editor, you can use the existing `change` DOM events. We added custom events in case of a multi-instance add, copy and delete operations, so you can listen to all the events on the instance.
-
-An example in Angular is:
-
-- `component.html`:
-```html
-<cedar-embeddable-editor
-  [config]="conf"
-  [templateObject]="template"
-  [instanceObject]="instance"
-  (change)="logChange($event)"
-></cedar-embeddable-editor>
-```
-
-- `component.ts`:
 ```typescript
-  logChange(event) {
-    console.log('CHANGE', event);
-  }
+import type { CeeConfig } from 'cedar-embeddable-editor';
+
+const ceeConfig: CeeConfig = {
+  terminologyBaseUrl: 'https://terminology.metadatacenter.org/',
+  bridgeBaseUrl: 'https://bridge.metadatacenter.org/',
+};
 ```
 
-### Viewer Mode
+For a different CEDAR deployment, replace both URLs with its service URLs. See
+the [configuration documentation](https://metadatacenter.readthedocs.io/en/latest/cedar-embeddable-editor/configuration/)
+for all available settings.
 
-CEE can be used as a viewer to display metadata instances. This can be achieved by the following configuration setting:
+#### Build the project and start the server
 
-```json
-"readOnlyMode": true
-```
-When used in this mode, users won't be able to manipulate the metadata instance but can only read it.
-## Example Applications
+1. Navigate to the CEE directory:
 
-There is a sample applications you can use to demonstrate how to embed and use CEE.
-Follow the links below to the demo application of your choice. The documentation for each demo application can be found in the README file of the corresponding application.
+   ```shell
+   cd <...>/<clone directory>/cedar-embeddable-editor/
+   ```
 
-### CEE Demo Angular
+2. Run these commands:
 
-This demo is written in Angular 2 and requires that framework to run properly.
+   ```shell
+   npm install
+   ng serve
+   ```
 
-https://github.com/metadatacenter/cedar-cee-demo/tree/main/cedar-cee-demo-angular-src
+3. In your browser, navigate to `http://localhost:4400/`. The app will
+   automatically reload if you change any of the source files.

package/bundle-manifest.json

@@ -0,0 +1,9 @@
+{
+  "strategy": "bundle",
+  "inputs": [
+    "main.js",
+    "polyfills.js"
+  ],
+  "bytes": 2183062,
+  "sha256": "bbcd976e2baed672c9a68851ebbadbed55544247daeb59adcd4422b79f219269"
+}