@grafana/create-plugin 7.12.3 → 7.14.0

package/templates/docs/panel/docs/README.md

@@ -0,0 +1,20 @@
+# {{{pluginName}}} documentation
+
+This folder is the documentation for **{{{pluginName}}}**. It's published on the Documentation tab of
+`grafana.com/grafana/plugins/{{pluginId}}/` with each plugin release. This README isn't published.
+
+To learn how plugin docs work and how to write them, read the
+[Add documentation to your plugin](https://grafana.com/developers/plugin-tools/how-to-guides/plugin-docs) guide.
+
+## Next steps
+
+1. Write the pages. Each section has a note that says what belongs there. **Or** let an AI agent draft them from your source code and README: commit your changes, then run `{{createPluginCmd}} add docs-content`. Review its work either way.
+2. Add screenshots, videos and figures where they help readers. Save them inside this folder, for example in `img/`, and link to them with a relative path. `docs:validate` checks their formats and sizes.
+3. Run `{{packageManagerName}} run docs:serve` to preview the docs. It also lists every section left to fill.
+
+## Commands
+
+```bash
+{{packageManagerName}} run docs:serve     # local preview at http://localhost:3001
+{{packageManagerName}} run docs:validate  # check your docs, including sections left to fill
+```

package/templates/docs/panel/docs/data-formats.md

@@ -0,0 +1,27 @@
+---
+title: Data formats
+description: "Learn what data formats the {{{yamlEscape pluginName}}} panel accepts."
+sidebar_position: 2
+---
+
+This document explains the data the {{{pluginName}}} panel needs from a query, so you can build a matching query or check your test data.
+
+## Supported data shape
+
+<!-- section-brief
+Fill this in: Describe the data frame shape {{{pluginName}}} expects: time series with N numeric fields, table with specific columns, single numeric value, geographic coordinates, log lines, etc. Be specific about field types and structure, because this is the contract dashboard authors rely on when building queries for the panel. Name the required field types (time, number, string, boolean) and any minimum/maximum field counts. After each shape, add a `#### Example` table whose headers are the field names the panel reads, with 3-5 rows of realistic values, so a reader can build a matching query or test data.
+-->
+
+## Field mapping
+
+<!-- section-brief
+Fill this in: Explain which incoming field plays which role in the visualization - for example "the first time-typed field is the x-axis, all numeric fields become series". If {{{pluginName}}} lets users explicitly pick field roles in the editor, document those controls here. Remove the section if mapping is fully automatic and not user-configurable.
+-->
+
+## Check what your query returns
+
+To see the data the panel receives, open the panel editor, click **Query inspector** and select the **Data** tab. You can also turn on **Table view** at the top of the panel editor to see the data as a table.
+
+## Reshape data that doesn't match
+
+If a query returns data in a different shape, you can reshape it without changing the query. Select the **Transform data** tab in the panel editor and add a transformation. For more information, refer to [Transform data](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/).

package/templates/docs/panel/docs/examples.md

@@ -0,0 +1,35 @@
+---
+title: Examples
+description: "Worked examples of the {{{yamlEscape pluginName}}} panel."
+sidebar_position: 4
+---
+
+To use an example, open your dashboard and go to **Dashboard settings** > **JSON Model**. Paste the excerpt into the `panels` array and click **Save changes**.
+
+<!-- section-brief
+Fill this in: Show concrete examples of {{{pluginName}}} configured for real use cases. When the repo has panels of this plugin's type in `provisioning/dashboards/*.json`, take the examples from those before inventing any. Express each example as a `dashboard.json` panel excerpt: `type` and `options`, plus `fieldConfig` and `targets` when the example depends on them. Leave out `id`, `gridPos`, `pluginVersion`, datasource UIDs and timestamps - they are specific to one dashboard and hide the settings that matter. Pair each example with a screenshot of the rendered visualization.
+
+If the repo ships a complete dashboard, for example under `provisioning/dashboards/`, link to it for readers who want the full JSON. Use the file's `https://` URL in your repository - relative links can't point outside the docs folder.
+-->
+
+## Basic example
+
+A panel excerpt in dashboard JSON has this shape:
+
+```json
+{
+  "type": "{{pluginId}}",
+  "options": {},
+  "targets": []
+}
+```
+
+<!-- section-brief
+Fill this in: Complete the excerpt above as the minimum viable {{{pluginName}}} configuration: the smallest `panels[]` entry that produces a meaningful visualization. Include only the settings it needs, plus a sample query in `targets` if the panel reads data. If the panel doesn't read data, remove `targets` from the excerpt. Pair with a screenshot of the result.
+-->
+
+## Common variations
+
+<!-- section-brief
+Fill this in: Show 1-3 alternate configurations that cover the most common ways dashboard authors use {{{pluginName}}} - different data shapes, option combinations, or display modes. Each variation is an excerpt showing only the settings that differ from the basic example, plus a screenshot. Explain in one line what each variation demonstrates.
+-->

package/templates/docs/panel/docs/index.md

@@ -0,0 +1,26 @@
+---
+title: Introduction
+description: "Where to start and what to read next in the {{{yamlEscape pluginName}}} docs."
+sidebar_position: 1
+---
+
+<!-- section-brief
+Fill this in: Write a short orientation for someone who already has {{{pluginName}}} installed and landed here from the Documentation tab. One or two sentences on what this section covers and how it's organized. Do not restate what the plugin does, its feature list, or its requirements - that's the README's job on the Overview tab, and this reader has already seen it there. Do not list every page in this folder either - the sidebar already does that; use prose to say what to read first and why.
+-->
+
+## Recommended path
+
+<!-- section-brief
+Fill this in: Give a short, ordered reading path for someone new to {{{pluginName}}} - two or three sentences, not a repeat of the sidebar. Point out the one or two pages most people need first and why, e.g. "Start with **Data formats** to shape your query results, then **Options** to configure the panel."
+-->
+
+## Common tasks
+
+- [Shape your query results for {{{pluginName}}}](./data-formats.md)
+- [Configure panel and field options](./options.md)
+- [See worked dashboard.json examples](./examples.md)
+- [Fix a panel that isn't rendering correctly](./troubleshooting.md)
+
+<!-- section-brief
+Fill this in: Keep the list above and adapt it to {{{pluginName}}}'s actual entry points - add, remove or reword tasks so each one matches a real job a user comes here to do. If you remove a page, remove its task too. This is a curated set of jobs, not a mechanical list of every file in this folder.
+-->

package/templates/docs/panel/docs/options.md

@@ -0,0 +1,53 @@
+---
+title: Options
+description: "Reference for {{{yamlEscape pluginName}}} panel options."
+sidebar_position: 3
+---
+
+To change these options, edit the panel and use the options pane.
+
+<!-- section-brief
+Fill this in: Reference the options {{{pluginName}}} exposes in the panel editor. Cover both the custom options the panel adds (via `setPanelOptions` in source) and the standard field options it enables (via `useFieldConfig`). Skip the sections below that don't apply to this panel - if there's no Standard field options block, no Tooltip and legend section etc., remove those headings entirely rather than leaving an empty brief.
+
+Do not redocument the framework-level standard options themselves (Min, Max, Unit, etc.) - Grafana's own docs cover those. The Standard field options section lists which ones are enabled, nothing more.
+-->
+
+## Panel options
+
+<!-- section-brief
+Fill this in: Emit a markdown table with these columns - one row per option registered through `setPanelOptions` in `src/module.ts`. Match the Grafana built-in panel docs style: https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/visualizations/logs/#logs-options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+
+- _Option_: the `name` value from the `setPanelOptions` `.add*({...})` call, verbatim.
+- _Type_: a short label for the editor the option uses, derived from the builder method (`addBooleanSwitch` → Toggle, `addSelect` → Select, `addNumberInput` → Number, `addFieldNamePicker` → Field picker). For a custom editor, name what it is, such as Color picker, rather than writing Custom.
+- _Default_: the value a reader sees in the panel editor, rendered as inline code. Resolve enum members, constants and translation calls to that value - `ClockMode.time` becomes `Time`. Keep the source expression only when it can't be resolved. When there is no default but the code falls back to a value while the option is unset, give that fallback value. Leave the cell empty only when there is neither.
+- _Description_: the `description` value, verbatim. If the verbatim text causes a `docs:validate` warning, reword it as little as possible and keep its meaning. When source has none, write one short sentence describing what the option does, based on how the panel code uses it. Don't guess beyond what the code shows.
+
+If the panel does not call `setPanelOptions`, remove this section entirely.
+-->
+
+## Standard field options
+
+For what each standard option does, refer to [Configure standard options](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-standard-options/).
+
+<!-- section-brief
+Fill this in: A bulleted list of the standard field options this panel enables - the entries from `useFieldConfig({ standardOptions: [...] })` in `src/module.ts`. If the panel calls `useFieldConfig()` or `useFieldConfig({})` without a `standardOptions` key, document this as "all standard options are enabled" and list the standard set.
+
+If the panel does not call `useFieldConfig` at all, remove this section entirely, including the link above.
+-->
+
+## Custom field options
+
+<!-- section-brief
+Fill this in: A table with the same shape as Panel options (Option / Type / Default / Description) but for the per-field overrides registered via `useFieldConfig({ useCustomConfig: builder => ... })`. These appear under the Overrides picker in the panel editor.
+
+If the panel does not register custom field options, remove this section entirely.
+-->
+
+## Tooltip and legend options
+
+<!-- section-brief
+Fill this in: Describe the tooltip and legend options {{{pluginName}}} exposes: hover behavior, the fields the tooltip shows and its formatting, and legend placement, values and calculations. Most of these already appear in the Panel options table above when they're registered via `setPanelOptions` with `category: ['Tooltip']` or `category: ['Legend']`, so use this section only for narrative context that doesn't fit in a table row. Remove this section if there is nothing extra to say beyond the table.
+-->

package/templates/docs/panel/docs/troubleshooting.md

@@ -0,0 +1,35 @@
+---
+title: Troubleshooting
+description: "Troubleshoot the {{{yamlEscape pluginName}}} panel."
+sidebar_position: 5
+---
+
+This page explains how to fix common issues when you use the {{{pluginName}}} panel. For the data the panel expects, refer to [Data formats](./data-formats.md).
+
+<!-- section-brief
+Fill this in: Replace this brief with one H2 per real failure mode, such as "Panel shows no data", "Wrong field selected" or "Rendering errors". Open each H2 with the symptom users see, then give the most likely cause and the steps to resolve it. Remove this brief and add nothing if there are no real failures to report.
+-->
+
+## Get more detail about an error
+
+To see the data the panel receives, open the panel editor, click **Query inspector** and select the **Data** tab.
+
+For errors in the panel itself, open the developer tools in your browser and check the console.
+
+## Get additional help
+
+If this page doesn't solve your problem:
+
+- Search the [Grafana community forums](https://community.grafana.com/).
+- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.
+
+<!-- section-brief
+Fill this in: Add links to the plugin's issue tracker to the list above.
+-->
+
+When you report an issue, include:
+
+- The Grafana and plugin versions.
+- The error message, with sensitive information removed.
+- The steps to reproduce the issue.
+- The panel options and a sample of the data it shows, with sensitive information removed.

package/templates/github/workflows/bundle-stats.yml

@@ -20,7 +20,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           persist-credentials: false
 

package/templates/github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
     env:
       GRAFANA_ACCESS_POLICY_TOKEN: $\{{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 {{#if_eq packageManagerName "pnpm"}}
@@ -35,7 +35,7 @@ jobs:
       - uses: pnpm/action-setup@v6
 {{/if_eq}}
       - name: Setup Node.js environment
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7
         with:
           node-version: '22'
           cache: '{{ packageManagerName }}'
@@ -62,13 +62,13 @@ jobs:
 
       - name: Setup Go environment
         if: steps.check-for-backend.outputs.has-backend == 'true'
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@v7
         with:
           go-version-file: go.mod
 
       - name: Lint backend
         if: steps.check-for-backend.outputs.has-backend == 'true'
-        uses: golangci/golangci-lint-action@82606bf257cbaff209d206a39f5134f0cfbfd2ee # v9.2.1
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
         with:
           version: latest
           args: ./...
@@ -146,7 +146,7 @@ jobs:
       matrix: $\{{ steps.resolve-versions.outputs.matrix }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           persist-credentials: false
 
@@ -164,7 +164,7 @@ jobs:
     name: e2e test $\{{ matrix.GRAFANA_IMAGE.name }}@$\{{ matrix.GRAFANA_IMAGE.VERSION }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
@@ -185,7 +185,7 @@ jobs:
       - uses: pnpm/action-setup@v6
 {{/if_eq}}
       - name: Setup Node.js environment
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7
         with:
           node-version: '22'
           cache: '{{ packageManagerName }}'

package/templates/github/workflows/is-compatible.yml

@@ -7,18 +7,18 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
 {{#if_eq packageManagerName "pnpm"}}
       # pnpm action uses the packageManager field in package.json to
       # understand which version to install.
-      - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 {{/if_eq}}
 
       - name: Setup Node.js environment
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: '22'
           cache: '{{ packageManagerName }}'

package/templates/github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       contents: write
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false