Merge branch 'master' into fix-toolbar-7036

.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2.1
 executors:
   pw-focal-development:
     docker:
-      - image: mcr.microsoft.com/playwright:v1.36.2-focal
+      - image: mcr.microsoft.com/playwright:v1.39.0-focal
     environment:
       NODE_ENV: development # Needed to ensure 'dist' folder created and devDependencies installed
       PERCY_POSTINSTALL_BROWSER: 'true' # Needed to store the percy browser in cache deps
@@ -162,7 +162,7 @@ jobs:
     steps:
       - build_and_install:
           node-version: <<parameters.node-version>>
-      - run: npx playwright@1.36.2 install #Necessary for bare ubuntu machine
+      - run: npx playwright@1.39.0 install #Necessary for bare ubuntu machine
       - run: |
           export $(cat src/plugins/persistence/couch/.env.ci | xargs)
           docker-compose -f src/plugins/persistence/couch/couchdb-compose.yaml up --detach

.cspell.json

@@ -487,7 +487,10 @@
     "blockquote",
     "blockquotes",
     "Blockquote",
-    "Blockquotes"
+    "Blockquotes",
+    "oger",
+    "lcovonly",
+    "gcov"
   ],
   "dictionaries": ["npm", "softwareTerms", "node", "html", "css", "bash", "en_US"],
   "ignorePaths": [
@@ -500,4 +503,4 @@
     "html-test-results",
     "test-results"
   ]
-}
+}

.github/dependabot.yml

@@ -5,6 +5,7 @@ updates:
     schedule:
       interval: 'weekly'
     open-pull-requests-limit: 10
+    rebase-strategy: 'disabled'
     labels:
       - 'pr:daveit'
       - 'pr:e2e'
@@ -28,10 +29,13 @@ updates:
         update-types: ['version-update:semver-patch']
       - dependency-name: '@types/lodash'
         update-types: ['version-update:semver-patch']
+      - dependency-name: 'marked'
+        update-types: ['version-update:semver-patch']
   - package-ecosystem: 'github-actions'
     directory: '/'
     schedule:
       interval: 'daily'
+    rebase-strategy: 'disabled'
     labels:
       - 'pr:daveit'
       - 'type:maintenance'

.github/workflows/codeql-analysis.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL

.github/workflows/e2e-couchdb.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: 'lts/hydrogen'
@@ -27,7 +27,7 @@ jobs:
           key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }}
           restore-keys: |
             ${{ runner.os }}-node-
-      
+
       - run: npm install --cache ~/.npm --no-audit --progress=false
 
       - name: Login to DockerHub
@@ -36,8 +36,8 @@ jobs:
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
-      
-      - run: npx playwright@1.36.2 install
+
+      - run: npx playwright@1.39.0 install
 
       - name: Start CouchDB Docker Container and Init with Setup Scripts
         run: |

.github/workflows/e2e-pr.yml

@@ -20,20 +20,20 @@ jobs:
           - ubuntu-latest
           - windows-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: 'lts/hydrogen'
-      
+
       - name: Cache NPM dependencies
         uses: actions/cache@v3
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }}
           restore-keys: |
             ${{ runner.os }}-node-
-            
-      - run: npx playwright@1.36.2 install
+
+      - run: npx playwright@1.39.0 install
       - run: npx playwright install chrome-beta
       - run: npm install --cache ~/.npm --no-audit --progress=false
       - run: npm run test:e2e:full -- --max-failures=40
@@ -65,4 +65,4 @@ jobs:
               });
             } catch (error) {
               core.warning(`Failed to remove ' + labelToRemove + ' label: ${error.message}`);
-            }
+            }

.github/workflows/npm-prerelease.yml

@@ -11,7 +11,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: lts/hydrogen
@@ -26,7 +26,7 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: lts/hydrogen

.github/workflows/pr-platform.yml

@@ -29,7 +29,7 @@ jobs:
 
     name: Node ${{ matrix.node_version }} - ${{ matrix.architecture }} on ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup node
         uses: actions/setup-node@v4

API.md

@@ -94,6 +94,9 @@ well as assets such as html, css, and images necessary for the UI.
 
 ## Starting an Open MCT application
 
+> [!WARNING]
+> Open MCT provides a development server via `webpack-dev-server` (`npm start`). **This should be used for development purposes only and should never be deployed to a production environment**.
+
 To start a minimally functional Open MCT application, it is necessary to
 include the Open MCT distributable, enable some basic plugins, and bootstrap
 the application. The tutorials walk through the process of getting Open MCT up
@@ -590,35 +593,108 @@ MinMax queries are issued by plots, and may be issued by other types as well.  T
 #### Telemetry Formats
 
 Telemetry format objects define how to interpret and display telemetry data.
-They have a simple structure:
-
-- `key`: A `string` that uniquely identifies this formatter.
-- `format`: A `function` that takes a raw telemetry value, and returns a
-  human-readable `string` representation of that value. It has one required
-  argument, and three optional arguments that provide context and can be used
-  for returning scaled representations of a value. An example of this is
-  representing time values in a scale such as the time conductor scale. There
-  are multiple ways of representing a point in time, and by providing a minimum
-  scale value, maximum scale value, and a count, it's possible to provide more
-  useful representations of time given the provided limitations.  
-  - `value`: The raw telemetry value in its native type.
-  - `minValue`: An **optional** argument specifying the minimum displayed
-      value.
-  - `maxValue`: An **optional** argument specifying the maximum displayed
-      value.
-  - `count`: An **optional** argument specifying the number of displayed
-      values.
-- `parse`: A `function` that takes a `string` representation of a telemetry
-  value, and returns the value in its native type. **Note** parse might receive an already-parsed value.  This function should be idempotent.
-- `validate`: A `function` that takes a `string` representation of a telemetry
-  value, and returns a `boolean` value indicating whether the provided string
-  can be parsed.
+They have a simple structure, provided here as a TypeScript interface:
+
+```ts
+interface Formatter {
+    key: string; // A string that uniquely identifies this formatter.
+
+    format: (
+        value: any, // The raw telemetry value in its native type.
+        minValue?: number, // An optional argument specifying the minimum displayed value.
+        maxValue?: number, // An optional argument specifying the maximum displayed value.
+        count?: number // An optional argument specifying the number of displayed values.
+    ) => string; // Returns a human-readable string representation of the provided value.
+
+    parse: (
+        value: string | any // A string representation of a telemetry value or an already-parsed value.
+    ) => any; // Returns the value in its native type. This function should be idempotent.
+
+    validate: (value: string) => boolean; // Takes a string representation of a telemetry value and returns a boolean indicating whether the provided string can be parsed.
+}
+```
+
+##### Built-in Formats
+
+Open MCT on its own defines a handful of built-in formats:
+
+###### **Number Format (default):** 
+
+Applied to data with `format: 'number'`
+```js
+valueMetadata = {
+    format: 'number'
+    // ...
+};
+```
+
+```ts
+interface NumberFormatter extends Formatter {
+    parse: (x: any) => number;
+    format: (x: number) => string;
+    validate: (value: any) => boolean;
+}
+```
+###### **String Format**:
+
+Applied to data with `format: 'string'`
+```js
+valueMetadata = {
+    format: 'string'
+    // ...
+};
+```
+```ts
+interface StringFormatter extends Formatter {
+    parse: (value: any) => string;
+    format: (value: string) => string;
+    validate: (value: any) => boolean;
+}
+```
+
+###### **Enum Format**:
+Applied to data with `format: 'enum'`
+```js
+valueMetadata = {
+    format: 'enum',
+    enumerations: [
+    {
+        value: 1,
+        string: 'APPLE'
+    }, 
+    {
+        value: 2,
+        string: 'PEAR',
+    },
+    {
+        value: 3,
+        string: 'ORANGE'
+    }]
+    // ...
+};
+```
+
+Creates a two-way mapping between enum string and value to be used in the `parse` and `format` methods.
+Ex:
+- `formatter.parse('APPLE') === 1;`
+- `formatter.format(1) === 'APPLE';`
+
+```ts
+interface EnumFormatter extends Formatter {
+    parse: (value: string) => string;
+    format: (value: number) => string;
+    validate: (value: any) => boolean;
+}
+```
 
 ##### Registering Formats
 
+Formats implement the following interface (provided here as TypeScript for simplicity):
+
+
 Formats are registered with the Telemetry API using the `addFormat` function. eg.
 
-``` javascript
+```javascript
 openmct.telemetry.addFormat({
     key: 'number-to-string',
     format: function (number) {

README.md

@@ -127,6 +127,8 @@ Each test suite generates a report in CircleCI. For a complete overview of testi
 
 Our code coverage is generated during the runtime of our unit, e2e, and visual tests. The combination of those reports is published to [codecov.io](https://app.codecov.io/gh/nasa/openmct/)
 
+For more on the specifics of our code coverage setup, [see](TESTING.md#code-coverage)
+
 # Glossary
 
 Certain terms are used throughout Open MCT with consistent meanings
@@ -182,3 +184,17 @@ You might still be using legacy API if your source code
 
 ### What should I do if I am using legacy API?
 Please refer to [the modern Open MCT API](https://nasa.github.io/openmct/documentation/). Post any questions to the [Discussions section](https://github.com/nasa/openmct/discussions) of the Open MCT GitHub repository.
+
+## Related Repos
+
+> [!NOTE]
+> Although Open MCT functions as a standalone project, it is primarily an extensible framework intended to be used as a dependency with users' own plugins and packaging. Furthermore, Open MCT is intended to be used with an HTTP server such as Apache or Nginx. A great example of hosting Open MCT with Apache is `openmct-quickstart` and can be found in the table below.
+
+| Repository | Description |
+| --- | --- |
+| [openmct-tutorial](https://github.com/nasa/openmct-tutorial) | A great place for beginners to learn how to use and extend Open MCT. |
+| [openmct-quickstart](https://github.com/scottbell/openmct-quickstart) | A working example of Open MCT integrated with Apache HTTP server, YAMCS telemetry, and Couch DB for persistence.
+| [Open MCT YAMCS Plugin](https://github.com/akhenry/openmct-yamcs) | Plugin for integrating YAMCS telemetry and command server with Open MCT. |
+| [openmct-performance](https://github.com/unlikelyzero/openmct-performance) | Resources for performance testing Open MCT. |
+| [openmct-as-a-dependency](https://github.com/unlikelyzero/openmct-as-a-dependency) | An advanced guide for users on how to build, develop, and test Open MCT when it's used as a dependency. |
+