@orangelogic/design-system 2.174.0 → 2.175.0

package/library/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orangelogic/design-system",
   "type": "module",
-  "version": "2.174.0",
+  "version": "2.175.0",
   "license": "UNLICENSED",
   "types": "library/types.d.ts",
   "scripts": {

package/library/packages/organisms/src/content-builder/plugins/{telemetry.d.ts → telemetry/index.d.ts}

@@ -1,5 +1,7 @@
 import { Editor } from 'grapesjs';
 
+export * from './metrics';
+export * from './measure';
 export type TelemetryPluginOptions = {
     bootStartedAt: number;
 };

package/library/packages/organisms/src/content-builder/{content-builder.telemetry.d.ts → plugins/telemetry/measure.d.ts}

@@ -1,28 +1,16 @@
 import { Component } from 'grapesjs';
+import { UiActionName } from './metrics';
 
-export declare const UiAction: {
-    readonly AddBlock: "add_block";
-    readonly ConfigureWorkflow: "configure_workflow";
-    readonly DeviceSwitch: "device_switch";
-    readonly DuplicateBlock: "duplicate_block";
-    readonly EditorBoot: "editor_boot";
-    readonly MoveBlock: "move_block";
-    readonly OpenConfig: "open_config";
-    readonly PickAsset: "pick_asset";
-    readonly PickAssetFormat: "pick_asset_format";
-    readonly PickDownloadFormat: "pick_download_format";
-    readonly Redo: "redo";
-    readonly RemoveBlock: "remove_block";
-    readonly RichTextEdit: "rich_text_edit";
-    readonly SaveConfig: "save_config";
-    readonly SelectBlock: "select_block";
-    readonly Undo: "undo";
-};
-export type UiActionName = (typeof UiAction)[keyof typeof UiAction];
 /** Mirrors the CMS5_BO.Data.MetricsIsEnabled parameter, passed in by the host VForm. */
 export declare function setEditorMetricsEnabled(enabled: boolean): void;
 /** Whether metrics are currently armed - the same flag `measureSync` and friends check. */
 export declare function isEditorMetricsEnabled(): boolean;
+/**
+ * Record one editor action.
+ *
+ * Mode is always 'edit' from here - the content builder only exists in edit mode. It is
+ * passed explicitly rather than defaulted downstream so the call says what it means.
+ */
 export declare function dispatch(action: string, durationMs: number, component: string, blockType?: string): void;
 /**
  * Derive the block-type label from a GrapesJS component.

package/library/packages/organisms/src/content-builder/plugins/telemetry/metrics.d.ts

@@ -0,0 +1,106 @@
+/**
+ * CMS5 browser metrics: what is measured, what the samples are called, and which label
+ * values are allowed to exist.
+ *
+ * Cortex owns the OpenTelemetry SDK, the exporter and the resource, and publishes an
+ * instrument factory on `window.OLTelemetry`. This module owns everything above that
+ * line. Only the factory crosses it, so the page runs one MeterProvider and one export
+ * stream however many bundles are loaded, and this repository ships no SDK of its own.
+ *
+ * The metric definitions and the label vocabularies used to live on the Cortex side, so
+ * that a frontend release could not introduce a new label value - and therefore new
+ * metric series - without a corresponding change there. They moved here because they
+ * describe this repository's own blocks and editor actions and went stale whenever it
+ * shipped without a matching Cortex change: a `cx-sb-` prefix rule once excluded fifteen
+ * of the twenty-one block types, including the two most common ones, so an ordinary page
+ * of headings and text produced no block metrics at all and simply looked idle.
+ *
+ * The bound those lists provided has moved with them, not been dropped. Every set below
+ * is closed, and a value outside it collapses to `unknown` rather than being dropped, so
+ * a missing entry shows up as a visible bucket in Grafana instead of silently
+ * disappearing. Adding a value here adds metric series - treat it as a change with a cost.
+ *
+ * When Cortex is older than the API, every entry point below is a no-op: the components
+ * behave exactly as they do with telemetry switched off.
+ *
+ * How things are *timed* lives in `./measure`; when the measurement is armed lives in
+ * `./index` (edit mode, the GrapesJS plugin) and `./content-render` (view mode).
+ */
+export declare const COMPONENT_CONTENT_BUILDER = "cx-content-builder";
+/** Stamped by CMS5_PageViewer_Content_VForm from the server's own edit-mode state. */
+export declare const METRICS_MARKER_SELECTOR = "[data-cms5-metrics=\"true\"]";
+/**
+ * Site-builder mode. The same page content is served in both, so without this label a
+ * block painted inside the editor canvas and the same block on the published page land in
+ * one series - and they are not the same thing. One is behind an authenticated editor
+ * with the builder bundle loaded; the other is what a visitor actually waits for.
+ */
+export declare const MODE_EDIT = "edit";
+export declare const MODE_VIEW = "view";
+export declare const UiAction: {
+    readonly AddBlock: "add_block";
+    readonly ConfigureWorkflow: "configure_workflow";
+    readonly DeviceSwitch: "device_switch";
+    readonly DuplicateBlock: "duplicate_block";
+    readonly EditorBoot: "editor_boot";
+    readonly MoveBlock: "move_block";
+    readonly OpenConfig: "open_config";
+    readonly PickAsset: "pick_asset";
+    readonly PickAssetFormat: "pick_asset_format";
+    readonly PickDownloadFormat: "pick_download_format";
+    readonly Redo: "redo";
+    readonly RemoveBlock: "remove_block";
+    readonly RichTextEdit: "rich_text_edit";
+    readonly SaveConfig: "save_config";
+    readonly SelectBlock: "select_block";
+    readonly Undo: "undo";
+};
+export type UiActionName = (typeof UiAction)[keyof typeof UiAction];
+/**
+ * Element name of every block the builder can place, mapped to its metric label.
+ *
+ * A table rather than a prefix rule, because block tags are not uniform: only six are
+ * named `cx-sb-*` and the rest reuse general-purpose design-system elements
+ * (`cx-header`, `cx-text`, `cx-gallery`, ...).
+ *
+ * The label is the GrapesJS block name, not the tag: that is the word the author sees in
+ * the block picker, and it survives a component being re-pointed at a different element.
+ * Gallery and Carousel are two picker entries backed by one element, so they necessarily
+ * share a label - the DOM cannot tell them apart.
+ */
+export declare const BLOCK_TAG_LABELS: Map<string, string>;
+/**
+ * The blocks whose render time is worth measuring on a published page: content the
+ * visitor is waiting for. The column containers are excluded - they resolve with the page
+ * itself, so timing them measures the framework rather than the content, and because one
+ * wraps every block they would dominate the sample.
+ */
+export declare const CONTENT_BLOCK_TAGS: string[];
+/**
+ * Blocks that render a placeholder and then fetch, so their Lit render completing says
+ * nothing about when the user actually sees content. These signal the real end instead.
+ */
+export declare const LOADING_BLOCK_TAGS: Set<string>;
+/**
+ * The mode the server said this page is in.
+ *
+ * Read from the stamp rather than inferred from the DOM: the editor mounts
+ * asynchronously, so anything guessed from the markup at load time would be a race.
+ */
+export declare function detectMode(container?: Element | null): string;
+export declare function blockLabelOf(tagName: string): string | undefined;
+export declare function recordUiAction(action: string, seconds: number, component: string, mode: string, blockType?: string): void;
+export declare function recordBlockRender(seconds: number, blockType: string | undefined, mode: string): void;
+export declare function recordContentRender(seconds: number, mode: string): void;
+export declare function countContentRenderAbandoned(mode: string): void;
+/**
+ * Tell Cortex which mode this page is in, so its own page-level histograms carry the
+ * dimension too.
+ *
+ * Page load, TTFB and the web vitals are recorded by Cortex, not here, and they need the
+ * split as much as these metrics do: opening a page for editing boots the editor inside
+ * the page load, so the authoring cost lands in the published page's timings unless the
+ * two populations can be told apart. Cortex cannot read this itself without knowing what
+ * CMS5 is, which is the arrangement this module exists to avoid.
+ */
+export declare function declarePageMode(mode: string): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orangelogic/design-system",
   "type": "module",
-  "version": "2.174.0",
+  "version": "2.175.0",
   "license": "UNLICENSED",
   "types": "library/types.d.ts",
   "scripts": {