@dosgato/templating 1.1.18 → 1.2.1

package/dist/apitemplate.d.ts

@@ -97,15 +97,31 @@ export interface APITemplate<DataType> {
      */
     getLinks?: LinkGatheringFn<DataType>;
     /**
-     * Each template must provide the text from any text or rich editor data it possesses, so that
-     * the text can be decomposed into words and indexed for fulltext searches. Any text returned
-     * by this function will also be scanned for links.
-     * Examples of text to include would be any text from data that's rendered as visible text content
+     * Each template must provide the plain text from its data so that it can be decomposed into
+     * words and indexed for fulltext searches. Any text returned by this function will also be
+     * scanned for links.
+     *
+     * Examples of text to include would be any plain text data that's rendered as visible content
      * but not things like dates and times.
+     *
+     * Rich text / HTML content should be returned via `getHtml` instead. Markup in `getFulltext`
+     * results will be indexed as-is, meaning tags and attributes will pollute the index.
+     *
      * @note You do not need to filter the text elements returned to ensure they're defined as that
      * can be done by the routine that calls `getFulltext`.
      */
     getFulltext?: FulltextGatheringFn<DataType>;
+    /**
+     * Return any HTML content from your template data so it can be parsed for indexing. The
+     * system will use cheerio to strip the markup and index the remaining text for fulltext
+     * search, and will also extract link targets (e.g. href attributes) before removing tags.
+     *
+     * This is preferable to stripping HTML yourself and returning it in getFulltext, because
+     * if you strip the markup yourself you'd also need to remember to extract and return links
+     * separately in getLinks. By returning the raw HTML here, both text and links are handled
+     * automatically in one place.
+     */
+    getHtml?: FulltextGatheringFn<DataType>;
     /**
      * Extra filters for this template
      *

package/dist/uitemplate.d.ts

@@ -211,35 +211,58 @@ export interface TracingInterface {
     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' */
+    /**
+     * The name of the UI component that is recording the event. This should help you track
+     * down where the event is being logged in the code.
+     *
+     * @example 'ActionPanel', 'PageEditor', 'ComponentDialog'
+     */
     eventType: string;
     /** The specific action the user took. Typically the label for the element that emits
      * the event.
      * @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
+     * 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.
+     * @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.
      * @example { hiddenLabel: action.hiddenLabel } // The aria label for an action element. */
     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. */
+/** 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 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' */
+    /**
+     * The sveltekit route the user is looking at when the event is triggered.
+     *
+     * Some dialogs will add the dialog name after a '#' for extra context, but this behavior is
+     * deprecated.
+     * @example '/pages', '/pages/[id]', '/pages/[id]#dialog' (deprecated) */
     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.
+    /**
+     * Identify a section of the screen to help identify what the user was looking at when
+     * taking the action. Very useful for tabs that do not have their own sveltekit routes.
+     *
+     * Also, if interacting inside a modal dialog that has a title,
+     * the title of the dialog could go here.
+     *
+     * Do not duplicate eventType here.
+     */
+    section?: string;
+    /**
+     * 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), specific enough to understand what the user
+     * was doing, but not so unique that an analytics search would never filter or group on it.
      *
-     * 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' */
+     * 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. When adding a component to a page, the templateKey of the
+     * component being added.
+     * @example '/site3-sandbox/about', 'hero-banner'
+     * */
     target: string;
 }
 interface AssetMetaDisplay {

package/package.json

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