@grafana/create-plugin 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# v1.8.0 (Tue Jul 11 2023)
+
+:tada: This release contains work from a new contributor! :tada:
+
+Thank you, Dominik Prokop ([@dprokop](https://github.com/dprokop)), for all your work!
+
+#### 🚀 Enhancement
+
+- Create Plugin: add readme best practice example [#298](https://github.com/grafana/plugin-tools/pull/298) ([@sympatheticmoose](https://github.com/sympatheticmoose))
+
+#### 🐛 Bug Fix
+
+- Create Plugin: Update scenes to latest version [#287](https://github.com/grafana/plugin-tools/pull/287) ([@dprokop](https://github.com/dprokop))
+
+#### Authors: 2
+
+- David Harris ([@sympatheticmoose](https://github.com/sympatheticmoose))
+- Dominik Prokop ([@dprokop](https://github.com/dprokop))
+
+---
+
 # v1.7.0 (Wed Jul 05 2023)
 
 #### 🚀 Enhancement

package/CONTRIBUTING.md

@@ -7,14 +7,14 @@ The following guidelines help you on how to start with the codebase and how to s
 
 ### Prerequisites
 
-You need to have `npm` or `yarn` installed.
+You need to have `npm` installed.
 
 ### Installing
 
 ```bash
 git clone git@github.com:grafana/plugin-tools.git
 cd plugin-tools
-yarn install
+npm install
 ```
 
 ## Overview
@@ -51,23 +51,23 @@ There are a collection of [commands](#commmands) to assist with developing `crea
 Below are the main commands used for developing `create-plugin`. They can be run by either `yarn workspace @grafana/create-plugin run <name_of_command>` or navigating to `packages/create-plugin` and running the command directly as detailed below.
 
 ```shell
-yarn build # used to build @grafana/create-plugin
+npm run build # used to build @grafana/create-plugin
 ```
 
 ```shell
-yarn dev # watches for changes to files and rebuilds @grafana/create-plugin automatically
+npm run dev # watches for changes to files and rebuilds @grafana/create-plugin automatically
 ```
 
 ```shell
-yarn dev-app # watches for changes and scaffolds an app plugin (in ./generated) for developing app configs
+npm run dev-app # watches for changes and scaffolds an app plugin (in ./generated) for developing app configs
 ```
 
 ```shell
-yarn dev-panel # watches for changes and scaffolds an app plugin (in ./generated) for developing panel configs
+npm run dev-panel # watches for changes and scaffolds an app plugin (in ./generated) for developing panel configs
 ```
 
 ```shell
-yarn dev-datasource # watches for changes and scaffolds an app plugin (in ./generated) for developing datasource configs
+npm run dev-datasource # watches for changes and scaffolds an app plugin (in ./generated) for developing datasource configs
 ```
 
 ### Conventions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/create-plugin",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "main": "index.js",
   "repository": {
     "directory": "packages/create-plugin",
@@ -66,5 +66,5 @@
   "engines": {
     "node": ">=16"
   },
-  "gitHead": "ec3651f12b05d7e8e4da515d272bfc1c568d5f21"
+  "gitHead": "13c1b8968b648533b252637706d632235abaa18e"
 }

package/templates/common/package.json

@@ -61,7 +61,8 @@
     "@grafana/data": "{{ grafanaVersion }}",
     "@grafana/runtime": "{{ grafanaVersion }}",
     "@grafana/ui": "{{ grafanaVersion }}",{{#if_eq pluginType "scenesapp"}}
-    "@grafana/scenes": "^0.11.0",{{/if_eq}}
+    "@grafana/schema": "10.0.1",
+    "@grafana/scenes": "^0.19.0",{{/if_eq}}
     "react": "17.0.2",
     "react-dom": "17.0.2",{{#if isAppType}}
     "react-router-dom": "^5.2.0",

package/templates/common/src/README.md

@@ -1,5 +1,50 @@
-<!-- This README file is going to be the one displayed on the Grafana.com website for your plugin -->
+<!-- This README file is going to be the one displayed on the Grafana.com website for your plugin. Uncomment and replace the content here before publishing.
 
+Remove any remaining comments before publishing as these may be displayed on Grafana.com -->
 # {{ titleCase pluginName }}
 
 {{ sentenceCase pluginDescription }}
+
+<!-- To help maximize the impact of your README and improve usability for users, we propose the following loose structure:
+
+**BEFORE YOU BEGIN**
+- Ensure all links are absolute URLs so that they will work when the README is displayed within Grafana and Grafana.com
+- Be inspired ✨ 
+  - [grafana-polystat-panel](https://github.com/grafana/grafana-polystat-panel)
+  - [volkovlabs-variable-panel](https://github.com/volkovlabs/volkovlabs-variable-panel)
+
+**ADD SOME BADGES**
+
+Badges convey useful information at a glance for users whether in the Catalog or viewing the source code. You can use the generator on [Shields.io](https://shields.io/badges/dynamic-json-badge) together with the Grafana.com API 
+to create dynamic badges that update automatically when you publish a new version to the marketplace.
+
+- For the logo field use 'grafana'.
+- Examples (label: query)
+  - Downloads: $.downloads
+  - Catalog Version: $.version
+  - Grafana Dependency: $.grafanaDependency
+  - Signature Type: $.versionSignatureType
+
+Full example: ![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?logo=grafana&query=$.version&url=https://grafana.com/api/plugins/grafana-polystat-panel&label=Marketplace&prefix=v&color=F47A20)
+
+Consider other [badges](https://shields.io/badges) as you feel appropriate for your project.
+
+## Overview / Introduction
+Provide one or more paragraphs as an introduction to your plugin to help users understand why they should use it.  
+
+Consider including screenshots:
+- in [plugin.json](https://grafana.com/docs/grafana/latest/developers/plugins/metadata/#info) include them as relative links.
+- in the README ensure they are absolute URLs.
+
+## Requirements
+List any requirements or dependencies they may need to run the plugin.
+
+## Getting Started
+Provide a quick start on how to configure and use the plugin.
+
+## Documentation
+If your project has dedicated documentation available for users, provide links here. For help in following Grafana's style recommendations for technical documentation, refer to our [Writer's Toolkit](https://grafana.com/docs/writers-toolkit/).
+
+## Contributing
+Do you want folks to contribute to the plugin or provide feedback through specific means? If so, tell them how!
+-->

package/templates/scenes-app/src/pages/HelloWorld/helloWorldScene.tsx

@@ -1,4 +1,4 @@
-import { EmbeddedScene, SceneFlexLayout, SceneFlexItem, VizPanel } from '@grafana/scenes';
+import { EmbeddedScene, SceneFlexLayout, SceneFlexItem, PanelBuilders } from '@grafana/scenes';
 
 export function getScene() {
   return new EmbeddedScene({
@@ -7,13 +7,7 @@ export function getScene() {
         new SceneFlexItem({
           width: '100%',
           height: 300,
-          body: new VizPanel({
-            title: 'Hello world panel',
-            pluginId: 'text',
-            options: {
-              content: 'Hello world! ',
-            },
-          }),
+          body: PanelBuilders.text().setTitle('Hello world panel').setOption('content', 'Hello world!').build(),
         }),
       ],
     }),

package/templates/scenes-app/src/pages/Home/scenes.tsx

@@ -1,6 +1,7 @@
 import {
   CustomVariable,
   EmbeddedScene,
+  PanelBuilders,
   SceneControlsSpacer,
   SceneFlexItem,
   SceneFlexLayout,
@@ -10,7 +11,6 @@ import {
   SceneTimeRange,
   SceneVariableSet,
   VariableValueSelectors,
-  VizPanel,
 } from '@grafana/scenes';
 import { DATASOURCE_REF } from '../../constants';
 import { CustomSceneObject } from './CustomSceneObject';
@@ -78,11 +78,11 @@ export function getBasicScene(templatised = true, seriesToShow = '__server_names
     body: new SceneFlexLayout({
       children: [
         new SceneFlexItem({
-          body: new VizPanel({
-            pluginId: 'timeseries',
+          minHeight: 300,
+          body: PanelBuilders.timeseries()
             // Title is using variable value
-            title: templatised ? '${seriesToShow}' : seriesToShow,
-          }),
+            .setTitle(templatised ? '${seriesToShow}' : seriesToShow)
+            .build(),
         }),
       ],
     }),

package/templates/scenes-app/src/pages/WithDrilldown/panels.tsx

@@ -1,125 +1,95 @@
-import { ReducerID, ThresholdsMode } from '@grafana/data';
+import { ReducerID } from '@grafana/data';
 import {
+  PanelBuilders,
   SceneByFrameRepeater,
   SceneDataNode,
   SceneDataTransformer,
   SceneFlexItem,
   SceneFlexLayout,
-  VizPanel,
 } from '@grafana/scenes';
+import { TableCellBackgroundDisplayMode, TableCellDisplayMode, ThresholdsMode } from '@grafana/schema';
 
 export function getRoomsTemperatureTable() {
-  return new VizPanel({
-    pluginId: 'table',
-    $data: new SceneDataTransformer({
-      transformations: [
-        {
-          id: 'reduce',
-          options: {
-            reducers: ['mean'],
-          },
-        },
-        {
-          id: 'organize',
-          options: {
-            excludeByName: {},
-            indexByName: {},
-            renameByName: {
-              Field: 'Room',
-              Mean: 'Average temperature',
-            },
-          },
+  const data = new SceneDataTransformer({
+    transformations: [
+      {
+        id: 'reduce',
+        options: {
+          reducers: ['mean'],
         },
-      ],
-    }),
-    displayMode: 'transparent',
-    title: 'Room temperature overview',
-    hoverHeader: true,
-    options: {
-      sortBy: ['Average temperature'],
-    },
-    fieldConfig: {
-      defaults: {
-        custom: {
-          align: 'auto',
-          cellOptions: {
-            type: 'auto',
+      },
+      {
+        id: 'organize',
+        options: {
+          excludeByName: {},
+          indexByName: {},
+          renameByName: {
+            Field: 'Room',
+            Mean: 'Average temperature',
           },
-          inspect: false,
-        },
-        mappings: [],
-        thresholds: {
-          mode: ThresholdsMode.Absolute,
-          steps: [
-            {
-              color: 'light-blue',
-              value: 0,
-            },
-            {
-              color: 'orange',
-              value: 19,
-            },
-            {
-              color: 'dark-red',
-              value: 26,
-            },
-          ],
-        },
-        color: {
-          mode: 'thresholds',
         },
       },
-      overrides: [
+    ],
+  });
+  return PanelBuilders.table()
+    .setTitle('Room temperature overview')
+    .setData(data)
+    .setHoverHeader(true)
+    .setDisplayMode('transparent')
+    .setOption('sortBy', [{ displayName: 'Average temperature' }])
+    .setThresholds({
+      mode: ThresholdsMode.Absolute,
+      steps: [
         {
-          matcher: {
-            id: 'byName',
-            options: 'Average temperature',
-          },
-          properties: [
-            {
-              id: 'unit',
-              value: 'celsius',
-            },
-            {
-              id: 'custom.cellOptions',
-              value: {
-                type: 'color-background',
-                mode: 'basic',
-              },
-            },
-            {
-              id: 'custom.width',
-              value: 200,
-            },
-            {
-              id: 'custom.align',
-              value: 'center',
-            },
-          ],
+          color: 'light-blue',
+          value: 0,
         },
         {
-          matcher: {
-            id: 'byName',
-            options: 'Room',
-          },
-          properties: [
-            {
-              id: 'links',
-              value: [
-                {
-                  title: 'Go to room overview',
-                  url: '${__url.path}/room/${__value.text}/temperature${__url.params}',
-                },
-              ],
-            },
-          ],
+          color: 'orange',
+          value: 19,
+        },
+        {
+          color: 'dark-red',
+          value: 26,
         },
       ],
-    },
-  });
+    })
+    .setColor({ mode: 'thresholds' })
+    .setCustomFieldConfig('align', 'auto')
+    .setCustomFieldConfig('cellOptions', { type: TableCellDisplayMode.Auto })
+    .setCustomFieldConfig('inspect', false)
+    .setOverrides((b) =>
+      b
+        .matchFieldsWithName('Average temperature')
+        .overrideUnit('celsius')
+        .overrideCustomFieldConfig('cellOptions', {
+          type: TableCellDisplayMode.ColorBackground,
+          mode: TableCellBackgroundDisplayMode.Basic,
+        })
+        .overrideCustomFieldConfig('width', 200)
+        .overrideCustomFieldConfig('align', 'center')
+        .matchFieldsWithName('Room')
+        .overrideLinks([
+          { title: 'Go to room overview', url: '${__url.path}/room/${__value.text}/temperature${__url.params}' },
+        ])
+    )
+    .build();
 }
 
 export function getRoomsTemperatureStats() {
+  const stat = PanelBuilders.stat()
+    .setUnit('celsius')
+    .setLinks([
+      {
+        title: 'Go to room temperature overview',
+        url: '${__url.path}/room/${__field.name}/temperature${__url.params}',
+      },
+      {
+        title: 'Go to room humidity overview',
+        url: '${__url.path}/room/${__field.name}/humidity${__url.params}',
+      },
+    ]);
+
   return new SceneByFrameRepeater({
     body: new SceneFlexLayout({
       direction: 'row',
@@ -130,57 +100,32 @@ export function getRoomsTemperatureStats() {
       return new SceneFlexItem({
         height: '50%',
         minWidth: '20%',
-        body: new VizPanel({
-          title: frame.name,
-          pluginId: 'stat',
-
-          $data: new SceneDataNode({
-            data: {
-              ...data,
-              series: [frame],
-            },
-          }),
-          fieldConfig: {
-            defaults: {
-              unit: 'celsius',
-              links: [
-                {
-                  title: 'Go to room temperature overview',
-                  url: '${__url.path}/room/${__field.name}/temperature${__url.params}',
-                },
-                {
-                  title: 'Go to room humidity overview',
-                  url: '${__url.path}/room/${__field.name}/humidity${__url.params}',
-                },
-              ],
-            },
-            overrides: [],
-          },
-        }),
+        body: stat
+          .setTitle(frame.name || '')
+          .setData(
+            new SceneDataNode({
+              data: {
+                ...data,
+                series: [frame],
+              },
+            })
+          )
+          .build(),
       });
     },
   });
 }
 
 export function getRoomTemperatureStatPanel(reducers: ReducerID[]) {
-  return new VizPanel({
-    pluginId: 'stat',
-    title: '',
-    $data: new SceneDataTransformer({
-      transformations: [
-        {
-          id: 'reduce',
-          options: {
-            reducers,
-          },
+  const data = new SceneDataTransformer({
+    transformations: [
+      {
+        id: 'reduce',
+        options: {
+          reducers,
         },
-      ],
-    }),
-    fieldConfig: {
-      defaults: {
-        unit: 'celsius',
       },
-      overrides: [],
-    },
+    ],
   });
+  return PanelBuilders.stat().setData(data).setUnit('celsius').build();
 }

package/templates/scenes-app/src/pages/WithDrilldown/scenes.tsx

@@ -3,12 +3,12 @@ import {
   EmbeddedScene,
   SceneFlexLayout,
   SceneQueryRunner,
-  VizPanel,
   SceneTimeRange,
   SceneTimePicker,
   SceneControlsSpacer,
   SceneRefreshPicker,
   SceneFlexItem,
+  PanelBuilders,
 } from '@grafana/scenes';
 import { DATASOURCE_REF } from '../../constants';
 import { getRoomTemperatureStatPanel } from './panels';
@@ -29,17 +29,7 @@ export function getTemperatureOverviewScene(roomName: string) {
       children: [
         new SceneFlexItem({
           height: 500,
-          body: new VizPanel({
-            title: 'Temperature over time',
-            pluginId: 'timeseries',
-
-            fieldConfig: {
-              defaults: {
-                unit: 'celsius',
-              },
-              overrides: [],
-            },
-          }),
+          body: PanelBuilders.timeseries().setTitle('Temperature over time').setUnit('celsius').build(),
         }),
         new SceneFlexItem({
           body: new SceneFlexLayout({
@@ -79,17 +69,7 @@ export function getHumidityOverviewScene(roomName: string) {
       children: [
         new SceneFlexItem({
           height: 500,
-          body: new VizPanel({
-            title: 'Humidity readings over time',
-            pluginId: 'timeseries',
-
-            fieldConfig: {
-              defaults: {
-                unit: 'humidity',
-              },
-              overrides: [],
-            },
-          }),
+          body: PanelBuilders.timeseries().setTitle('Humidity over time').setUnit('humidity').build(),
         }),
       ],
     }),