@dosgato/templating 1.2.0 → 1.2.2

package/dist/uitemplate.d.ts

@@ -210,37 +210,66 @@ export interface TracingInterface {
     endTransaction?: (name: string, details: any, env?: TracingEnvironment) => void;
     event?: (name: string, details: any, env?: TracingEnvironment) => void;
 }
-export interface BaseEvent {
-    /** The larger UI area the user is interacting with that the event is emitted from.
-     * @example 'ActionPanel', 'PageEditor', 'ComponentDialog' */
+/** Common model for user interaction events in DosGato, designed to capture contextually
+ * important properties for analytics and metrics logging and create enough shared structure
+ * to make it easy to generate meaningful reports and insights. */
+export interface UserEvent {
+    /**
+     * The sveltekit route the user is navigated to when the event is triggered. This should
+     * always be a sveltekit route with the param abstracted out. additionalProperties might have
+     * a full path to the page being acted on.
+     * @example '/pages', '/pages/[id]'
+     */
+    screen: string;
+    /**
+     * An identifier for the log statement in the code. This should be human readable
+     * but also help developers find the log statement in the codebase.
+     *
+     * @example 'ActionPanel', 'PageEditor', 'ComponentDialog'
+     */
     eventType: string;
-    /** The specific action the user took. Typically the label for the element that emits
-     * the event.
+    /**
+     * The specific action the user took. If you are logging a button click, it's probably the
+     * button label. If you are logging a page view, whether it's a first page view or a CSR navigation.
+     * If you're logging a modal, 'Open', 'Success', 'Failed', 'Cancel', etc.
      * @example 'Add Page', 'Edit Page', 'Preview', 'Cancel Preview' */
     action: string;
-    /** Additional data points specific to a particular event type's context. These should
-     * be significant enough to understanding the event to merrit adding additional columns
+    /**
+     * The target of the action reported in the `action` property.
+     *
+     * Each component that logs an event should consider the best value to place here. It's best
+     * if it's human-readable (avoid numeric and UUIDs) and consistent enough to use in lots of different
+     * reports. In DosGato, we try to record the path to the page, asset, or data item being manipulated,
+     * even if the action is more fine-grained, like adding a component to a specific area. This allows us
+     * to make reports about pages being edited regardless of the type of edit. We can store the path to the
+     * area or component being edited in `additionalProperties`.
+     *
+     * For example: When moving a page, the path of the page being moved. When moving many pages, the
+     * path of the page being moved into.
+     * @example '/site3-sandbox/about'
+     * */
+    target?: string;
+    /**
+     * Additional data points specific to a particular event type's context. These should
+     * be significant enough to understanding the event to merit adding additional columns
      * in tools like elastic-search.
-     * @warning This is NOT a catch-all property.
-     * @example { hiddenLabel: action.hiddenLabel } // The aria label for an action element. */
+     *
+     * @warning This is NOT a catch-all property. It should be used for metrics an analytics
+     * report would be likely to filter or group by. Every new property name likely forces the
+     * analytics database to add a new column that is null for every event that doesn't use it.
+     * @example { path: 'areas.main' } // when adding a component, the area we're adding to
+     */
     additionalProperties?: Record<string, string | undefined>;
-}
-/** Events triggered by user interactions with interface elements in DosGato. This interface
- * is intended to provide a common model for succinctly expressing the contextually important
- * properties of these events to loggers that can be pointed to analytics and metrics services. */
-export interface UserEvent extends BaseEvent {
-    /** The page, screen, or dialog the user is looking at in which the associated event emitter is
-     * in context to.
-     * @example '/pages', '/pages/[id]', '/pages/[id]/dialog' */
-    screen: string;
-    /** The target the emitted event is to trigger actions on.
-     * Each page/screen, or dialog, needs to set their target for what events in it are targeted
-     * to act on in in its context.
+    /**
+     * In some cases `screen` may be too ambiguous to understand where the user was. For instance,
+     * a screen might have tabs at the top of the page that switch between very different functionalities
+     * without changing the sveltekit route. Or a dashboard might have multiple independent widgets and
+     * we'd like to know which they were interacting with.
      *
-     * For example: The page in the page tree of the Pages screen that ActionPanel actions,
-     * such as edit or preview, will act on.
-     * @example '/site3-sandbox/about' */
-    target: string;
+     * This property can be used in those situations to disambiguate. Use it when the deprecated
+     * `{ screen: '/pages/[id]#tab1' }` format would have made sense pre-deprecation.
+     */
+    section?: string;
 }
 interface AssetMetaDisplay {
     component: UITemplate['dialog'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {