@grafana/assistant 0.0.7 → 0.0.9

package/README.md

@@ -84,6 +84,48 @@ openAssistant({
 });
 ```
 
+### Providing Page-Specific Context
+
+You can register context items that are automatically included when the assistant is opened on pages matching specific URL patterns. The `providePageContext` function works like `useState` - it returns a setter function that allows you to update the context dynamically:
+
+```typescript
+import { providePageContext, createContext } from '@grafana/assistant';
+
+// Create initial context for dashboard pages
+const dashboardContext = createContext('structured', {
+  data: {
+    name: 'Dashboard Context',
+    pageType: 'dashboard',
+    capabilities: ['view', 'edit', 'share'],
+    help: 'Use the assistant to analyze dashboard data, create queries, or troubleshoot issues.'
+  }
+});
+
+// Register context for all dashboard pages and get a setter function
+const setContext = providePageContext('/d/*', [dashboardContext]);
+
+// Later, dynamically update the context based on user interactions or data changes
+setContext([
+  dashboardContext,
+  createContext('structured', {
+    data: {
+      name: 'Panel Context',
+      selectedPanel: 'cpu-usage-panel',
+      panelType: 'graph'
+    }
+  })
+]);
+
+// The context will automatically be included when openAssistant is called from dashboard pages
+openAssistant({ 
+  prompt: 'Help me analyze this dashboard' 
+  // Current context is automatically included
+});
+
+// Clean up when no longer needed
+setContext.unregister();
+```
+
 ### Creating Context Items
 
 The `createContext` function allows you to create structured context items that provide the assistant with additional information about your Grafana resources.
@@ -230,6 +272,36 @@ Creates a context item that can be passed to the assistant to provide additional
 
 **Returns:** A `ChatContextItem` that can be passed to `openAssistant`
 
+#### `providePageContext(urlPattern: string | RegExp, initialContext: ChatContextItem[]): ((context: ChatContextItem[]) => void) & { unregister: () => void }`
+
+Registers context items for specific pages based on URL patterns. Returns a setter function to update the context dynamically, similar to `useState`. The context will be automatically included when the assistant is opened on pages matching the pattern.
+
+**Parameters:**
+- `urlPattern` - URL pattern (string with wildcards or RegExp) to match against page URLs
+  - String patterns support `*` (match any characters) and `**` (match any path segments)
+  - RegExp patterns provide full regex matching capabilities
+- `initialContext` - Initial array of `ChatContextItem` to provide when the pattern matches
+
+**Returns:** A setter function to update the context, with an `unregister` method attached for cleanup
+
+**Examples:**
+```typescript
+// String patterns - returns setter function
+const setDashboardContext = providePageContext('/d/*', initialContext); // Match any dashboard
+const setExploreContext = providePageContext('/explore**', initialContext); // Match explore and subpaths
+
+// RegExp patterns  
+const setSpecificContext = providePageContext(/^\/d\/[a-zA-Z0-9]+$/, initialContext); // Match specific dashboard format
+
+// Update context dynamically
+setDashboardContext([...newContext]);
+
+// Cleanup when done
+setDashboardContext.unregister();
+```
+
+
+
 ### Sidebar Types
 
 #### `OpenAssistantProps`
@@ -238,11 +310,16 @@ Creates a context item that can be passed to the assistant to provide additional
 type OpenAssistantProps = {
   prompt?: string;
   context?: ChatContextItem[];
+  includePageContext?: boolean;
 };
 ```
 
 Configuration object for opening the assistant.
 
+- `prompt` - Optional initial prompt to display
+- `context` - Optional context items to provide  
+- `includePageContext` - Whether to automatically include page context for the current URL (defaults to true)
+
 #### `ChatContextItem`
 
 ```typescript
@@ -254,6 +331,8 @@ type ChatContextItem = {
 
 A context item that provides structured information to the assistant.
 
+
+
 ### Context Types
 
 #### Datasource Context Parameters

package/dist/context/index.d.ts

@@ -4,4 +4,5 @@ export * from './dashboard';
 export * from './datasource';
 export * from './factory';
 export * from './label';
+export * from './page';
 export * from './types';

package/dist/context/page.d.ts

@@ -0,0 +1,29 @@
+import { ChatContextItem } from './types';
+export interface PageContextRegistration {
+    id: string;
+    urlPattern: string | RegExp;
+    context: ChatContextItem[];
+}
+/**
+ * Registers context items for specific pages based on URL patterns.
+ * Returns a setter function to update the context dynamically, similar to useState.
+ *
+ * If a registration with the same URL pattern already exists, it will be replaced.
+ *
+ * @param urlPattern - URL pattern (string or RegExp) to match against page URLs
+ * @param initialContext - Initial array of ChatContextItem to provide when the pattern matches
+ * @returns A setter function to update the context, with an unregister method attached
+ */
+export declare function providePageContext(urlPattern: string | RegExp, initialContext: ChatContextItem[]): ((context: ChatContextItem[]) => void) & {
+    unregister: () => void;
+};
+/**
+ * React hook for providing page context that automatically cleans up on unmount.
+ * This is the recommended way to use page context in React components.
+ *
+ * @param urlPattern - URL pattern (string or RegExp) to match against page URLs
+ * @param initialContext - Initial array of ChatContextItem to provide when the pattern matches
+ * @returns A setter function to update the context
+ */
+export declare function useProvidePageContext(urlPattern: string | RegExp, initialContext?: ChatContextItem[]): (context: ChatContextItem[]) => void;
+export declare function usePageContext(): ChatContextItem[];

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createContext, DashboardNodeData, DatasourceNodeData, FolderNodeData, ItemDataType, LabelNameNodeData, LabelValueNodeData, StructuredNodeData, TreeNode, } from './context/index';
+export { createContext, DashboardNodeData, DatasourceNodeData, FolderNodeData, ItemDataType, LabelNameNodeData, LabelValueNodeData, StructuredNodeData, TreeNode, providePageContext, PageContextRegistration, usePageContext, } from './context/index';
 export * from './functions';
 export * from './hook';
 export * from './plugin';

package/dist/index.js

@@ -1 +1 @@
-(()=>{"use strict";var e,a={d:(e,t)=>{for(var s in t)a.o(t,s)&&!a.o(e,s)&&Object.defineProperty(e,s,{enumerable:!0,get:t[s]})},o:(e,a)=>Object.prototype.hasOwnProperty.call(e,a),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},t={};function s(e){let a=5381;for(let t=0;t<e.length;t++)a=(a<<5)+a+e.charCodeAt(t);return(a>>>0).toString(16)}a.r(t),a.d(t,{CALLBACK_EXTENSION_POINT:()=>p,DashboardNodeData:()=>d,DatasourceNodeData:()=>i,FolderNodeData:()=>n,ItemDataType:()=>e,LabelNameNodeData:()=>l,LabelValueNodeData:()=>u,StructuredNodeData:()=>o,closeAssistant:()=>x,createContext:()=>h,getExposeAssistantFunctionsConfig:()=>m,isAssistantAvailable:()=>U,newFunctionNamespace:()=>f,openAssistant:()=>D,useAssistant:()=>w}),function(e){e.Unknown="unknown",e.Datasource="datasource",e.LabelName="label_name",e.LabelValue="label_value",e.Dashboard="dashboard",e.DashboardFolder="dashboard_folder",e.Structured="structured"}(e||(e={}));class r{constructor(e){this.params=e,this.id=s(e.id)}formatForLLM(a){return{type:e.Unknown,codeElementIds:a,data:{name:this.params.text}}}}class o{constructor(e){this.params=e,this.id=s(JSON.stringify(e.data))}formatForLLM(a){return{type:e.Structured,codeElementIds:a,data:this.params.data}}}class d extends r{constructor(e){super({...e,id:e.dashboardUid}),this.dashboardUid=e.dashboardUid,this.dashboardTitle=e.dashboardTitle,this.folderUid=e.folderUid,this.folderTitle=e.folderTitle}formatForLLM(a){return{type:e.Dashboard,codeElementIds:a,data:{name:this.dashboardTitle,dashboardUid:this.dashboardUid,dashboardTitle:this.dashboardTitle,folderUid:this.folderUid,folderTitle:this.folderTitle}}}}class n extends r{constructor(e){super({...e,id:e.folderUid}),this.folderUid=e.folderUid,this.folderTitle=e.folderTitle}formatForLLM(a){return{type:e.DashboardFolder,codeElementIds:a,data:{name:this.folderTitle,folderUid:this.folderUid,folderTitle:this.folderTitle}}}}class i extends r{constructor(e){super({...e,id:e.datasourceUid}),this.datasourceUid=e.datasourceUid,this.datasourceType=e.datasourceType,this.datasourceName=e.datasourceName}formatForLLM(a){return{type:e.Datasource,codeElementIds:a,data:{name:this.datasourceName,uid:this.datasourceUid,type:this.datasourceType}}}}class l extends r{constructor(e){super({...e,id:`${e.datasourceUid}-${e.labelName}`}),this.datasourceUid=e.datasourceUid,this.datasourceType=e.datasourceType,this.labelName=e.labelName}formatForLLM(a){return{type:e.LabelName,codeElementIds:a,data:{name:this.labelName,datasourceUid:this.datasourceUid,datasourceType:this.datasourceType,labelName:this.labelName}}}}class u extends r{constructor(e){super({...e,id:`${e.datasourceUid}-${e.labelName}-${e.labelValue}`}),this.datasourceUid=e.datasourceUid,this.datasourceType=e.datasourceType,this.labelName=e.labelName,this.labelValue=e.labelValue}formatForLLM(a){return{type:e.LabelValue,codeElementIds:a,data:{name:this.labelValue,datasourceUid:this.datasourceUid,datasourceType:this.datasourceType,labelName:this.labelName,labelValue:this.labelValue}}}}const c={[e.Datasource]:"database",[e.LabelName]:"database",[e.LabelValue]:"database",[e.Dashboard]:"dashboard",[e.DashboardFolder]:"folder",[e.Unknown]:"circle-mono",[e.Structured]:"gf-grid"};function b(a,t){return a===e.Datasource?t.datasourceName:a===e.LabelName?t.labelName:a===e.LabelValue?t.labelValue:a===e.Dashboard?t.dashboardTitle:a===e.DashboardFolder?t.folderTitle:a===e.Structured?t.data.name:"Given Context"}function h(e,a){var t,s;const h=function(e,a){switch(e){case"datasource":return new i(a);case"label_name":return new l(a);case"label_value":return new u(a);case"dashboard":return new d(a);case"dashboard_folder":return new n(a);case"structured":return new o(a);case"unknown":return new r(a);default:return console.error(`Unknown context type: ${e}`),new r(a)}}(e,a);return{node:{id:h.id,name:null!==(t=a.title)&&void 0!==t?t:b(e,a),icon:null!==(s=a.icon)&&void 0!==s?s:c[e],navigable:!1,selectable:!0,data:h},occurrences:[]}}const p="grafana-assistant-app/callback/v0-alpha";function f(e,a){return{namespace:e,functions:a}}function m(e){return{title:"callback",targets:[p],fn:()=>e.map(e=>({namespace:e.namespace,functions:e.functions}))}}const y=require("react"),T=require("@grafana/runtime"),N=require("rxjs");function U(){return(0,T.getObservablePluginLinks)({extensionPointId:"grafana/extension-sidebar/v0-alpha"}).pipe((0,N.map)(e=>e.some(e=>"grafana-assistant-app"===e.pluginId&&"Grafana Assistant"===e.title)))}const L=require("@grafana/data");class g extends L.BusEventWithPayload{}g.type="open-extension-sidebar";class v extends L.BusEventBase{}function D(e){!function(e,a,t){const s=new g({pluginId:"grafana-assistant-app",componentTitle:"Grafana Assistant",props:t});(0,T.getAppEvents)().publish(s)}(0,0,{initialPrompt:e.prompt,initialContext:e.context})}function x(){!function(){const e=new v;(0,T.getAppEvents)().publish(e)}()}function w(){const[e,a]=(0,y.useState)(!1);return(0,y.useEffect)(()=>{const e=U().subscribe(e=>a(e));return()=>{e.unsubscribe()}},[]),[e,e?D:void 0,e?x:void 0]}v.type="close-extension-sidebar",module.exports=t})();
+(()=>{"use strict";var e,t={d:(e,a)=>{for(var n in a)t.o(a,n)&&!t.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:a[n]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},a={};function n(e){let t=5381;for(let a=0;a<e.length;a++)t=(t<<5)+t+e.charCodeAt(a);return(t>>>0).toString(16)}t.r(a),t.d(a,{CALLBACK_EXTENSION_POINT:()=>N,DashboardNodeData:()=>o,DatasourceNodeData:()=>i,FolderNodeData:()=>d,ItemDataType:()=>e,LabelNameNodeData:()=>l,LabelValueNodeData:()=>c,StructuredNodeData:()=>r,closeAssistant:()=>V,createContext:()=>f,getExposeAssistantFunctionsConfig:()=>D,isAssistantAvailable:()=>S,newFunctionNamespace:()=>U,openAssistant:()=>A,providePageContext:()=>y,useAssistant:()=>M,usePageContext:()=>x}),function(e){e.Unknown="unknown",e.Datasource="datasource",e.LabelName="label_name",e.LabelValue="label_value",e.Dashboard="dashboard",e.DashboardFolder="dashboard_folder",e.Structured="structured"}(e||(e={}));class s{constructor(e){this.params=e,this.id=n(e.id)}formatForLLM(t){return{type:e.Unknown,codeElementIds:t,data:{name:this.params.text}}}}class r{constructor(e){this.params=e,this.id=n(JSON.stringify(e.data))}formatForLLM(t){return{type:e.Structured,codeElementIds:t,data:this.params.data}}}class o extends s{constructor(e){super({...e,id:e.dashboardUid}),this.dashboardUid=e.dashboardUid,this.dashboardTitle=e.dashboardTitle,this.folderUid=e.folderUid,this.folderTitle=e.folderTitle}formatForLLM(t){return{type:e.Dashboard,codeElementIds:t,data:{name:this.dashboardTitle,dashboardUid:this.dashboardUid,dashboardTitle:this.dashboardTitle,folderUid:this.folderUid,folderTitle:this.folderTitle}}}}class d extends s{constructor(e){super({...e,id:e.folderUid}),this.folderUid=e.folderUid,this.folderTitle=e.folderTitle}formatForLLM(t){return{type:e.DashboardFolder,codeElementIds:t,data:{name:this.folderTitle,folderUid:this.folderUid,folderTitle:this.folderTitle}}}}class i extends s{constructor(e){super({...e,id:e.datasourceUid}),this.datasourceUid=e.datasourceUid,this.datasourceType=e.datasourceType,this.datasourceName=e.datasourceName}formatForLLM(t){return{type:e.Datasource,codeElementIds:t,data:{name:this.datasourceName,uid:this.datasourceUid,type:this.datasourceType}}}}class l extends s{constructor(e){super({...e,id:`${e.datasourceUid}-${e.labelName}`}),this.datasourceUid=e.datasourceUid,this.datasourceType=e.datasourceType,this.labelName=e.labelName}formatForLLM(t){return{type:e.LabelName,codeElementIds:t,data:{name:this.labelName,datasourceUid:this.datasourceUid,datasourceType:this.datasourceType,labelName:this.labelName}}}}class c extends s{constructor(e){super({...e,id:`${e.datasourceUid}-${e.labelName}-${e.labelValue}`}),this.datasourceUid=e.datasourceUid,this.datasourceType=e.datasourceType,this.labelName=e.labelName,this.labelValue=e.labelValue}formatForLLM(t){return{type:e.LabelValue,codeElementIds:t,data:{name:this.labelValue,datasourceUid:this.datasourceUid,datasourceType:this.datasourceType,labelName:this.labelName,labelValue:this.labelValue}}}}const u={[e.Datasource]:"database",[e.LabelName]:"database",[e.LabelValue]:"database",[e.Dashboard]:"dashboard",[e.DashboardFolder]:"folder",[e.Unknown]:"circle-mono",[e.Structured]:"gf-grid"};function p(t,a){return t===e.Datasource?a.datasourceName:t===e.LabelName?a.labelName:t===e.LabelValue?a.labelValue:t===e.Dashboard?a.dashboardTitle:t===e.DashboardFolder?a.folderTitle:t===e.Structured?a.data.name:"Given Context"}function f(e,t){var a,n;const f=function(e,t){switch(e){case"datasource":return new i(t);case"label_name":return new l(t);case"label_value":return new c(t);case"dashboard":return new o(t);case"dashboard_folder":return new d(t);case"structured":return new r(t);case"unknown":return new s(t);default:return console.error(`Unknown context type: ${e}`),new s(t)}}(e,t);return{node:{id:f.id,name:null!==(a=t.title)&&void 0!==a?a:p(e,t),icon:null!==(n=t.icon)&&void 0!==n?n:u[e],navigable:!1,selectable:!0,data:f},occurrences:[]}}const h=require("@grafana/runtime"),b=require("react"),m=[],v="grafana-assistant:page-context-sync",w="grafana-assistant:page-context-update",g="grafana-assistant:page-context-remove",L="grafana-assistant:location-changed";let E=!1;function y(e,t){const a=m.findIndex((t=>{return a=t.urlPattern,n=e,"string"==typeof a&&"string"==typeof n?a===n:a instanceof RegExp&&n instanceof RegExp&&a.source===n.source&&a.flags===n.flags;var a,n}));let n;-1!==a?(n=m[a],n.context=[...t]):(n={id:`page-context-${Date.now()}-${Math.random().toString(36).substr(2,9)}`,urlPattern:e,context:[...t]},m.push(n)),window.dispatchEvent(new CustomEvent(w,{detail:n})),window.dispatchEvent(new CustomEvent(v,{detail:{registry:m}}));const s=e=>{const t=m.findIndex((e=>e.id===n.id));-1!==t&&(m[t].context=[...e],window.dispatchEvent(new CustomEvent(w,{detail:m[t]})))};return s.unregister=()=>{const e=m.findIndex((e=>e.id===n.id));-1!==e&&(m.splice(e,1),window.dispatchEvent(new CustomEvent(g,{detail:{id:n.id}})))},s}function x(){const[e,t]=(0,b.useState)([]),a=(0,h.useLocationService)(),n=(0,b.useRef)("");return(0,b.useEffect)((()=>{const e=()=>{const e=function(e,t){if(!e)return[];const a=[];for(const n of t)T(e,n.urlPattern)&&a.push(...n.context);return a}(a.getLocation().pathname,m);t(e)},s=()=>{e()},r=t=>{var n;const s=null===(n=t.detail)||void 0===n?void 0:n.pathname;s&&s===a.getLocation().pathname&&e()},o=a.getLocationObservable().subscribe((t=>{const a=t.pathname;a!==n.current&&(n.current=a,function(e){window.dispatchEvent(new CustomEvent(L,{detail:{pathname:e}}))}(a),e())}));return e(),window.addEventListener(v,s),window.addEventListener(w,s),window.addEventListener(g,s),window.addEventListener(L,r),()=>{o.unsubscribe(),window.removeEventListener(v,s),window.removeEventListener(w,s),window.removeEventListener(g,s),window.removeEventListener(L,r)}}),[a]),e}function T(e,t){if(t instanceof RegExp)return t.test(e);if("string"==typeof t){const a=t.replace(/\*\*/g,".*").replace(/\*/g,"[^/]*").replace(/\?/g,".");return new RegExp(`^${a}$`).test(e)}return!1}E||(window.addEventListener(v,(e=>{var t;const a=null===(t=e.detail)||void 0===t?void 0:t.registry;if(a){const e=new Set(m.map((e=>e.id))),t=a.filter((t=>!e.has(t.id)));m.push(...t)}})),window.addEventListener(w,(e=>{const t=e.detail;if(t){const e=m.findIndex((e=>e.id===t.id));-1!==e?m[e]=t:m.push(t)}})),window.addEventListener(g,(e=>{var t;const a=null===(t=e.detail)||void 0===t?void 0:t.id;if(a){const e=m.findIndex((e=>e.id===a));-1!==e&&m.splice(e,1)}})),E=!0);const N="grafana-assistant-app/callback/v0-alpha";function U(e,t){return{namespace:e,functions:t}}function D(e){return{title:"callback",targets:[N],fn:()=>e.map((e=>({namespace:e.namespace,functions:e.functions})))}}const I=require("rxjs");function S(){return(0,h.getObservablePluginLinks)({extensionPointId:"grafana/extension-sidebar/v0-alpha"}).pipe((0,I.map)((e=>e.some((e=>"grafana-assistant-app"===e.pluginId&&"Grafana Assistant"===e.title)))))}const C=require("@grafana/data");class F extends C.BusEventWithPayload{}F.type="open-extension-sidebar";class P extends C.BusEventBase{}function A(e){!function(e,t,a){const n=new F({pluginId:"grafana-assistant-app",componentTitle:"Grafana Assistant",props:a});(0,h.getAppEvents)().publish(n)}(0,0,{initialPrompt:e.prompt,initialContext:e.context})}function V(){!function(){const e=new P;(0,h.getAppEvents)().publish(e)}()}function M(){const[e,t]=(0,b.useState)(!1);return(0,b.useEffect)((()=>{const e=S().subscribe((e=>t(e)));return()=>{e.unsubscribe()}}),[]),[e,e?A:void 0,e?V:void 0]}P.type="close-extension-sidebar",module.exports=a})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/assistant",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Type definitions and helper functions for Grafana Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,10 +9,9 @@
   ],
   "scripts": {
     "prebuild": "rm -rf dist",
-    "build:dev": "webpack --config webpack.config.cjs --mode development && tsc --emitDeclarationOnly",
     "build": "webpack --config webpack.config.cjs --mode production && tsc --emitDeclarationOnly",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build"
+    "dev": "webpack --config webpack.config.cjs --mode development",
+    "clean": "rm -rf dist"
   },
   "keywords": [
     "grafana",
@@ -25,7 +24,7 @@
   "dependencies": {},
   "devDependencies": {
     "react": "18.3.1",
-    "rxjs": "7.8.1",
+    "rxjs": "7.8.2",
     "ts-loader": "^9.0.0",
     "typescript": "^5.0.0",
     "webpack": "^5.0.0",
@@ -37,9 +36,9 @@
   "peerDependencies": {
     "react": ">=18.0.0",
     "rxjs": ">=7.0.0",
-    "@grafana/data": ">=12.0.0",
-    "@grafana/runtime": ">=12.0.0",
+    "@grafana/data": ">=12.1.0",
+    "@grafana/runtime": ">=12.1.0",
     "@grafana/scenes": ">=5.41.0",
-    "@grafana/ui": ">=12.0.0"
+    "@grafana/ui": ">=12.1.0"
   }
 }