@perses-dev/plugin-system 0.55.0-beta.1 → 0.55.0-beta.11

package/dist/components/PluginEditor/plugin-editor-api.js

@@ -10,10 +10,10 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-import { useState, useRef, useEffect } from 'react';
-import { produce } from 'immer';
-import { usePlugin, usePluginRegistry } from '../../runtime';
-import { useEvent } from '../../utils';
+import { produce } from "immer";
+import { useState, useRef, useEffect } from "react";
+import { usePlugin, usePluginRegistry } from "../../runtime/index.js";
+import { useEvent } from "../../utils/index.js";
 /**
  * Returns the state/handlers that power the `PluginEditor` component. Useful for custom components that want to provide
  * a different UI, but want the same behavior of changing `kind` and `spec` together on plugin kind changes. Also
@@ -63,7 +63,12 @@ import { useEvent } from '../../utils';
         value.selection,
         defaultPluginKind
     ]);
-    const { data: plugin, isFetching, error } = usePlugin(pendingSelection?.type, pendingSelection?.kind || '');
+    // Load the pending plugin honoring the pinned version/registry, so the initial options come from the exact
+    // implementation the definition will use rather than from the latest one.
+    const { data: plugin, isFetching, error } = usePlugin(pendingSelection?.type, pendingSelection?.kind || '', {
+        version: pendingSelection?.metadata?.version,
+        registry: pendingSelection?.metadata?.registry
+    });
     useEffect(()=>{
         // Nothing to do if no new plugin kind is pending
         if (!pendingSelection) return;

package/dist/components/PluginEditor/plugin-editor-api.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/PluginEditor/plugin-editor-api.ts"],"sourcesContent":["// Copyright The Perses Authors\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nimport { BoxProps } from '@mui/material';\nimport { UnknownSpec } from '@perses-dev/spec';\nimport { useState, useRef, useEffect } from 'react';\nimport { produce } from 'immer';\nimport { PanelPlugin, PluginType } from '../../model';\nimport { PluginKindSelectProps } from '../PluginKindSelect';\nimport { PluginSpecEditorProps } from '../PluginSpecEditor';\nimport { usePlugin, usePluginRegistry } from '../../runtime';\nimport { useEvent } from '../../utils';\n\nexport interface PluginEditorSelection {\n  type: PluginType;\n  kind: string;\n}\n\nexport interface PluginEditorValue {\n  selection: PluginEditorSelection;\n  spec: UnknownSpec;\n}\n\n// Props on MUI Box that we don't want people to pass because we're either redefining them or providing them in\n// this component\ntype OmittedMuiProps = 'children' | 'value' | 'onChange';\n\nexport interface PluginEditorProps extends Omit<BoxProps, OmittedMuiProps> {\n  pluginTypes: PluginType[];\n  pluginKindLabel: string;\n  value: PluginEditorValue;\n  isReadonly?: boolean;\n  withRunQueryButton?: boolean;\n  filteredQueryPlugins?: string[];\n  onChange: (next: PluginEditorValue) => void;\n  onRunQuery?: () => void;\n}\n\nexport interface PluginEditorRef {\n  flushChanges?: () => void;\n}\n\ntype PreviousSpecState = Record<string, Record<string, UnknownSpec>>;\ntype HideQueryEditorState = Record<string, boolean>;\n\n/**\n * Props needed by the usePluginEditor hook.\n */\nexport type UsePluginEditorProps = Pick<PluginEditorProps, 'pluginTypes' | 'value' | 'onChange'> & {\n  onHideQueryEditorChange?: (isHidden: boolean) => void;\n};\n\n/**\n * Returns the state/handlers that power the `PluginEditor` component. Useful for custom components that want to provide\n * a different UI, but want the same behavior of changing `kind` and `spec` together on plugin kind changes. Also\n * remembers previous `spec` values that it's seen, allowing and restores those values if a user switches the plugin\n * kind back.\n */\nexport function usePluginEditor(props: UsePluginEditorProps): {\n  pendingSelection?: PluginEditorSelection;\n  isLoading: boolean;\n  error: Error | null;\n  onSelectionChange: (s: PluginEditorSelection) => void;\n  onSpecChange: (next: UnknownSpec) => void;\n  rememberCurrentSpecState: () => void;\n} {\n  // eslint-disable-next-line @typescript-eslint/no-empty-function\n  const { pluginTypes, value, onHideQueryEditorChange = (): void => {} } = props; // setting onHideQueryEditorChange to empty function here because useEvent requires a function\n\n  // Keep a stable reference, so we don't run the effect below when we don't need to\n  const onChange = useEvent(props.onChange);\n  const onHideQuery = useEvent(onHideQueryEditorChange);\n\n  // The previous spec state for PluginType and kind and a helper function for remembering current values\n  const prevSpecState = useRef<PreviousSpecState>({\n    [value.selection.type]: { [value.selection.kind]: value.spec },\n  });\n  const rememberCurrentSpecState = useEvent(() => {\n    let byPluginType = prevSpecState.current[value.selection.type];\n    if (byPluginType === undefined) {\n      byPluginType = {};\n      prevSpecState.current[value.selection.type] = byPluginType;\n    }\n    byPluginType[value.selection.kind] = value.spec;\n  });\n\n  // The previous hide query state for each panel kind\n  const hideQueryState = useRef<HideQueryEditorState>({\n    [value.selection.kind]: false,\n  });\n\n  const { defaultPluginKinds } = usePluginRegistry();\n  const defaultPluginType = pluginTypes[0];\n  const defaultPluginKind = defaultPluginType ? defaultPluginKinds?.[defaultPluginType] : undefined;\n  const defaultPluginSelection =\n    defaultPluginType && defaultPluginKind\n      ? {\n          type: defaultPluginType,\n          kind: defaultPluginKind,\n        }\n      : undefined;\n  const initPendingSelection = !value.selection && defaultPluginSelection ? defaultPluginSelection : undefined;\n\n  // When kind changes and we haven't loaded that plugin before, we will need to enter a \"pending\" state so that we\n  // can generate proper initial spec values that match the new plugin kind\n  const [pendingSelection, setPendingSelection] = useState<PluginEditorSelection | undefined>(initPendingSelection);\n\n  // Take a default kind in case user write explicitly an empty kind in the initial value\n  useEffect(() => {\n    if (value.selection.kind === '') {\n      value.selection.kind = defaultPluginKind || '';\n    }\n  }, [value.selection, defaultPluginKind]);\n\n  const { data: plugin, isFetching, error } = usePlugin(pendingSelection?.type, pendingSelection?.kind || '');\n\n  useEffect(() => {\n    // Nothing to do if no new plugin kind is pending\n    if (!pendingSelection) return;\n\n    // Can't get spec value until we have a plugin\n    if (plugin === undefined || isFetching) return;\n\n    // Fire an onChange to change to the pending kind with initial values from the plugin\n    rememberCurrentSpecState();\n    onChange({\n      selection: pendingSelection,\n      spec: plugin.createInitialOptions ? plugin.createInitialOptions() : {},\n    });\n\n    if (pendingSelection.type === 'Panel') {\n      const panelPlugin = plugin as PanelPlugin;\n      hideQueryState.current[pendingSelection.kind] = !!panelPlugin.hideQueryEditor;\n      if (!!panelPlugin.hideQueryEditor !== hideQueryState.current[value.selection.kind]) {\n        onHideQuery(!!panelPlugin.hideQueryEditor);\n      }\n    }\n    setPendingSelection(undefined);\n  }, [\n    pendingSelection,\n    plugin,\n    isFetching,\n    rememberCurrentSpecState,\n    onChange,\n    onHideQuery,\n    hideQueryState,\n    value.selection,\n  ]);\n\n  /**\n   * When the user tries to change the plugin kind, make sure we have the correct spec for that plugin kind before we\n   * make the switch.\n   */\n  const onSelectionChange: PluginKindSelectProps['onChange'] = (nextSelection) => {\n    // If we already have state for this plugin type/kind from a previous selection, just use it\n    const previousState = prevSpecState.current[nextSelection.type]?.[nextSelection.kind];\n    if (previousState !== undefined) {\n      rememberCurrentSpecState();\n      onChange({\n        selection: nextSelection,\n        spec: previousState,\n      });\n    } else {\n      // Otherwise, kick off the async loading process\n      setPendingSelection(nextSelection);\n    }\n\n    if (\n      nextSelection.type === 'Panel' &&\n      hideQueryState.current[nextSelection.kind] !== undefined &&\n      hideQueryState.current[value.selection.kind] !== hideQueryState.current[nextSelection.kind]\n    ) {\n      onHideQuery(!!hideQueryState.current[nextSelection.kind]);\n    }\n  };\n\n  /**\n   * Spec changes are independent and always just set the spec state.\n   */\n  const onSpecChange: PluginSpecEditorProps['onChange'] = (next) => {\n    onChange(\n      produce(value, (draft) => {\n        draft.spec = next;\n      })\n    );\n  };\n\n  return {\n    pendingSelection,\n    isLoading: isFetching,\n    error,\n    onSelectionChange,\n    onSpecChange,\n    rememberCurrentSpecState,\n  };\n}\n"],"names":["useState","useRef","useEffect","produce","usePlugin","usePluginRegistry","useEvent","usePluginEditor","props","pluginTypes","value","onHideQueryEditorChange","onChange","onHideQuery","prevSpecState","selection","type","kind","spec","rememberCurrentSpecState","byPluginType","current","undefined","hideQueryState","defaultPluginKinds","defaultPluginType","defaultPluginKind","defaultPluginSelection","initPendingSelection","pendingSelection","setPendingSelection","data","plugin","isFetching","error","createInitialOptions","panelPlugin","hideQueryEditor","onSelectionChange","nextSelection","previousState","onSpecChange","next","draft","isLoading"],"mappings":"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"}
+{"version":3,"sources":["../../../src/components/PluginEditor/plugin-editor-api.ts"],"sourcesContent":["// Copyright The Perses Authors\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nimport type { BoxProps } from '@mui/material';\nimport type { DatasourceSpec, PluginDefinitionMetadata, UnknownSpec } from '@perses-dev/spec';\nimport { produce } from 'immer';\nimport { useState, useRef, useEffect } from 'react';\n\nimport type { PanelPlugin, PluginType } from '../../model';\nimport { usePlugin, usePluginRegistry } from '../../runtime';\nimport { useEvent } from '../../utils';\nimport type { PluginKindSelectProps } from '../PluginKindSelect';\nimport type { PluginSpecEditorProps } from '../PluginSpecEditor';\n\nexport interface PluginEditorSelection {\n  type: PluginType;\n  kind: string;\n  /**\n   * Optional plugin definition metadata (version and/or registry), matching the `metadata` field of a spec\n   * `Definition`. Only set when the user explicitly picks a specific version/registry of a plugin that has several of\n   * them available. When omitted, the latest available version is used.\n   */\n  metadata?: PluginDefinitionMetadata;\n}\n\nexport interface PluginEditorValue {\n  selection: PluginEditorSelection;\n  spec: UnknownSpec;\n}\n\n// Props on MUI Box that we don't want people to pass because we're either redefining them or providing them in\n// this component\ntype OmittedMuiProps = 'children' | 'value' | 'onChange';\n\nexport interface PluginEditorProps extends Omit<BoxProps, OmittedMuiProps> {\n  pluginTypes: PluginType[];\n  pluginKindLabel: string;\n  value: PluginEditorValue;\n  isReadonly?: boolean;\n  withRunQueryButton?: boolean;\n  filteredQueryPlugins?: string[];\n  onChange: (next: PluginEditorValue) => void;\n  onRunQuery?: () => void;\n  testConnection?: (spec: DatasourceSpec, healthCheckPath: string) => Promise<void>;\n}\n\nexport interface PluginEditorRef {\n  flushChanges?: () => void;\n}\n\ntype PreviousSpecState = Record<string, Record<string, UnknownSpec>>;\ntype HideQueryEditorState = Record<string, boolean>;\n\n/**\n * Props needed by the usePluginEditor hook.\n */\nexport type UsePluginEditorProps = Pick<PluginEditorProps, 'pluginTypes' | 'value' | 'onChange'> & {\n  onHideQueryEditorChange?: (isHidden: boolean) => void;\n};\n\n/**\n * Returns the state/handlers that power the `PluginEditor` component. Useful for custom components that want to provide\n * a different UI, but want the same behavior of changing `kind` and `spec` together on plugin kind changes. Also\n * remembers previous `spec` values that it's seen, allowing and restores those values if a user switches the plugin\n * kind back.\n */\nexport function usePluginEditor(props: UsePluginEditorProps): {\n  pendingSelection?: PluginEditorSelection;\n  isLoading: boolean;\n  error: Error | null;\n  onSelectionChange: (s: PluginEditorSelection) => void;\n  onSpecChange: (next: UnknownSpec) => void;\n  rememberCurrentSpecState: () => void;\n} {\n  // eslint-disable-next-line @typescript-eslint/no-empty-function\n  const { pluginTypes, value, onHideQueryEditorChange = (): void => {} } = props; // setting onHideQueryEditorChange to empty function here because useEvent requires a function\n\n  // Keep a stable reference, so we don't run the effect below when we don't need to\n  const onChange = useEvent(props.onChange);\n  const onHideQuery = useEvent(onHideQueryEditorChange);\n\n  // The previous spec state for PluginType and kind and a helper function for remembering current values\n  const prevSpecState = useRef<PreviousSpecState>({\n    [value.selection.type]: { [value.selection.kind]: value.spec },\n  });\n  const rememberCurrentSpecState = useEvent(() => {\n    let byPluginType = prevSpecState.current[value.selection.type];\n    if (byPluginType === undefined) {\n      byPluginType = {};\n      prevSpecState.current[value.selection.type] = byPluginType;\n    }\n    byPluginType[value.selection.kind] = value.spec;\n  });\n\n  // The previous hide query state for each panel kind\n  const hideQueryState = useRef<HideQueryEditorState>({\n    [value.selection.kind]: false,\n  });\n\n  const { defaultPluginKinds } = usePluginRegistry();\n  const defaultPluginType = pluginTypes[0];\n  const defaultPluginKind = defaultPluginType ? defaultPluginKinds?.[defaultPluginType] : undefined;\n  const defaultPluginSelection =\n    defaultPluginType && defaultPluginKind\n      ? {\n          type: defaultPluginType,\n          kind: defaultPluginKind,\n        }\n      : undefined;\n  const initPendingSelection = !value.selection && defaultPluginSelection ? defaultPluginSelection : undefined;\n\n  // When kind changes and we haven't loaded that plugin before, we will need to enter a \"pending\" state so that we\n  // can generate proper initial spec values that match the new plugin kind\n  const [pendingSelection, setPendingSelection] = useState<PluginEditorSelection | undefined>(initPendingSelection);\n\n  // Take a default kind in case user write explicitly an empty kind in the initial value\n  useEffect(() => {\n    if (value.selection.kind === '') {\n      value.selection.kind = defaultPluginKind || '';\n    }\n  }, [value.selection, defaultPluginKind]);\n\n  // Load the pending plugin honoring the pinned version/registry, so the initial options come from the exact\n  // implementation the definition will use rather than from the latest one.\n  const {\n    data: plugin,\n    isFetching,\n    error,\n  } = usePlugin(pendingSelection?.type, pendingSelection?.kind || '', {\n    version: pendingSelection?.metadata?.version,\n    registry: pendingSelection?.metadata?.registry,\n  });\n\n  useEffect(() => {\n    // Nothing to do if no new plugin kind is pending\n    if (!pendingSelection) return;\n\n    // Can't get spec value until we have a plugin\n    if (plugin === undefined || isFetching) return;\n\n    // Fire an onChange to change to the pending kind with initial values from the plugin\n    rememberCurrentSpecState();\n    onChange({\n      selection: pendingSelection,\n      spec: plugin.createInitialOptions ? plugin.createInitialOptions() : {},\n    });\n\n    if (pendingSelection.type === 'Panel') {\n      const panelPlugin = plugin as PanelPlugin;\n      hideQueryState.current[pendingSelection.kind] = !!panelPlugin.hideQueryEditor;\n      if (!!panelPlugin.hideQueryEditor !== hideQueryState.current[value.selection.kind]) {\n        onHideQuery(!!panelPlugin.hideQueryEditor);\n      }\n    }\n    setPendingSelection(undefined);\n  }, [\n    pendingSelection,\n    plugin,\n    isFetching,\n    rememberCurrentSpecState,\n    onChange,\n    onHideQuery,\n    hideQueryState,\n    value.selection,\n  ]);\n\n  /**\n   * When the user tries to change the plugin kind, make sure we have the correct spec for that plugin kind before we\n   * make the switch.\n   */\n  const onSelectionChange: PluginKindSelectProps['onChange'] = (nextSelection) => {\n    // If we already have state for this plugin type/kind from a previous selection, just use it\n    const previousState = prevSpecState.current[nextSelection.type]?.[nextSelection.kind];\n    if (previousState !== undefined) {\n      rememberCurrentSpecState();\n      onChange({\n        selection: nextSelection,\n        spec: previousState,\n      });\n    } else {\n      // Otherwise, kick off the async loading process\n      setPendingSelection(nextSelection);\n    }\n\n    if (\n      nextSelection.type === 'Panel' &&\n      hideQueryState.current[nextSelection.kind] !== undefined &&\n      hideQueryState.current[value.selection.kind] !== hideQueryState.current[nextSelection.kind]\n    ) {\n      onHideQuery(!!hideQueryState.current[nextSelection.kind]);\n    }\n  };\n\n  /**\n   * Spec changes are independent and always just set the spec state.\n   */\n  const onSpecChange: PluginSpecEditorProps['onChange'] = (next) => {\n    onChange(\n      produce(value, (draft) => {\n        draft.spec = next;\n      }),\n    );\n  };\n\n  return {\n    pendingSelection,\n    isLoading: isFetching,\n    error,\n    onSelectionChange,\n    onSpecChange,\n    rememberCurrentSpecState,\n  };\n}\n"],"names":["produce","useState","useRef","useEffect","usePlugin","usePluginRegistry","useEvent","usePluginEditor","props","pluginTypes","value","onHideQueryEditorChange","onChange","onHideQuery","prevSpecState","selection","type","kind","spec","rememberCurrentSpecState","byPluginType","current","undefined","hideQueryState","defaultPluginKinds","defaultPluginType","defaultPluginKind","defaultPluginSelection","initPendingSelection","pendingSelection","setPendingSelection","data","plugin","isFetching","error","version","metadata","registry","createInitialOptions","panelPlugin","hideQueryEditor","onSelectionChange","nextSelection","previousState","onSpecChange","next","draft","isLoading"],"mappings":"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"}

package/dist/components/PluginKindSelect/PluginKindSelect.d.ts

@@ -1,12 +1,25 @@
-/// <reference types="react" />
-import { TextFieldProps } from '@mui/material';
-import { PluginType } from '../../model';
-import { PluginEditorSelection } from '../PluginEditor';
+import type { TextFieldProps } from '@mui/material';
+import type { PluginType } from '../../model';
+import type { PluginEditorSelection } from '../PluginEditor';
 export interface PluginKindSelectProps extends Omit<TextFieldProps, 'value' | 'onChange' | 'children'> {
     filteredQueryPlugins?: string[];
     pluginTypes: PluginType[];
     value?: PluginEditorSelection;
     onChange?: (s: PluginEditorSelection) => void;
+    /**
+     * When true, a plugin that has more than one version available is listed with a `<display name> - Latest` option and
+     * once per version, labeled `<display name> - <version>`. Selecting a specific version sets `metadata.version` on the
+     * selection so it can be persisted on the definition, while selecting Latest leaves the version unpinned. A plugin
+     * with a single available version is listed without a version, so it keeps resolving to the latest one. Defaults to
+     * false.
+     */
+    enableVersionSelection?: boolean;
+    /**
+     * When true, a plugin that is available in more than one registry is listed once per registry, labeled
+     * `<display name> (<registry>)`. Selecting such an option sets `metadata.registry` on the selection. A plugin
+     * available in a single registry is listed without it. Defaults to false.
+     */
+    enableRegistrySelection?: boolean;
 }
 /**
  * Displays a MUI Select input for selecting a plugin's kind from a list of all the available plugins of some specific

package/dist/components/PluginKindSelect/PluginKindSelect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PluginKindSelect.d.ts","sourceRoot":"","sources":["../../../src/components/PluginKindSelect/PluginKindSelect.tsx"],"names":[],"mappings":";AAaA,OAAO,EAAuB,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;IACpG,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,wHAyD3B,CAAC"}
+{"version":3,"file":"PluginKindSelect.d.ts","sourceRoot":"","sources":["../../../src/components/PluginKindSelect/PluginKindSelect.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMpD,OAAO,KAAK,EAA4B,UAAU,EAAE,MAAM,aAAa,CAAC;AAGxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;IACpG,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAsFD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,wHAkH3B,CAAC"}

package/dist/components/PluginKindSelect/PluginKindSelect.js

@@ -1,4 +1,3 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Copyright The Perses Authors
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,9 +10,90 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-import { MenuItem, TextField } from '@mui/material';
-import { forwardRef, useCallback, useMemo } from 'react';
-import { useListPluginMetadata } from '../../runtime';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MenuItem, TextField } from "@mui/material";
+import { forwardRef, useCallback, useMemo } from "react";
+import { useListPluginMetadata } from "../../runtime/index.js";
+import { comparePluginVersions } from "../../utils/index.js";
+function getVariant(metadata) {
+    return {
+        version: metadata.metadata?.version ?? metadata.module?.version,
+        registry: metadata.metadata?.registry ?? metadata.module?.registry
+    };
+}
+function getVariantKey(variant) {
+    return `${variant.version ?? ''}:${variant.registry ?? ''}`;
+}
+/**
+ * Build the selectable entries of a plugin kind. A version (resp. registry) is only part of the entries when the caller
+ * enabled its selection *and* the plugin is actually installed in more than one version (resp. registry): there is
+ * nothing to pick otherwise, and leaving it out keeps the definition floating on the latest version.
+ */ function getGroupOptions(group, enableVersionSelection, enableRegistrySelection) {
+    const showVersion = enableVersionSelection && group.hasMultipleVersions;
+    const showRegistry = enableRegistrySelection && group.hasMultipleRegistries;
+    if (!showVersion && !showRegistry) {
+        const selection = {
+            type: group.type,
+            kind: group.kind
+        };
+        return [
+            {
+                selection,
+                label: group.displayName,
+                value: selectionToOptionValue(selection)
+            }
+        ];
+    }
+    const options = [];
+    const seen = new Set();
+    if (showVersion) {
+        const selection = {
+            type: group.type,
+            kind: group.kind
+        };
+        options.push({
+            selection,
+            label: `${group.displayName} - Latest`,
+            value: selectionToOptionValue(selection)
+        });
+        seen.add(getVariantKey({}));
+    }
+    for (const variant of group.variants){
+        const version = showVersion ? variant.version : undefined;
+        const registry = showRegistry ? variant.registry : undefined;
+        const metadata = {
+            ...version ? {
+                version
+            } : {},
+            ...registry ? {
+                registry
+            } : {}
+        };
+        // Variants that only differ on a field we don't display collapse into a single entry.
+        const key = getVariantKey({
+            version,
+            registry
+        });
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        const selection = {
+            type: group.type,
+            kind: group.kind,
+            ...version || registry ? {
+                metadata
+            } : {}
+        };
+        const label = `${group.displayName}${version ? ` - ${version}` : ''}${registry ? ` (${registry})` : ''}`;
+        options.push({
+            selection,
+            label,
+            value: selectionToOptionValue(selection)
+        });
+    }
+    return options;
+}
 /**
  * Displays a MUI Select input for selecting a plugin's kind from a list of all the available plugins of some specific
  * plugin types. (e.g. "Show a list of all the Panel plugins", or "Show a list of all the Variable plugins", or "Show
@@ -21,19 +101,78 @@ import { useListPluginMetadata } from '../../runtime';
  * The value of the select is the kind of the plugin, but you can also listen to the `onPluginTypeChange` event to know
  * when the user changes the plugin type (it fires at start for the default value.)
  */ export const PluginKindSelect = /*#__PURE__*/ forwardRef((props, ref)=>{
-    const { pluginTypes, value: propValue, onChange, filteredQueryPlugins, ...others } = props;
+    const { pluginTypes, value: propValue, onChange, filteredQueryPlugins, enableVersionSelection = false, enableRegistrySelection = false, ...others } = props;
     const { data, isLoading } = useListPluginMetadata(pluginTypes);
     const sortedData = useMemo(()=>{
-        if (filteredQueryPlugins?.length) {
-            return data?.filter((i)=>filteredQueryPlugins.includes(i.spec.name))?.sort((a, b)=>a.spec.display.name.localeCompare(b.spec.display.name));
-        }
-        return data?.sort((a, b)=>a.spec.display.name.localeCompare(b.spec.display.name));
+        const filtered = filteredQueryPlugins?.length ? data?.filter((i)=>filteredQueryPlugins.includes(i.spec.name)) : data;
+        return filtered?.toSorted((a, b)=>a.spec.display.name.localeCompare(b.spec.display.name));
     }, [
         data,
         filteredQueryPlugins
     ]);
+    // Group the metadata by plugin kind, collecting all the variants each one is installed under (newest version first).
+    const kindGroups = useMemo(()=>{
+        const groups = new Map();
+        for (const metadata of sortedData ?? []){
+            const key = `${metadata.kind}:${metadata.spec.name}`;
+            let group = groups.get(key);
+            if (group === undefined) {
+                group = {
+                    type: metadata.kind,
+                    kind: metadata.spec.name,
+                    displayName: metadata.spec.display.name,
+                    variants: [],
+                    hasMultipleVersions: false,
+                    hasMultipleRegistries: false
+                };
+                groups.set(key, group);
+            }
+            const variant = getVariant(metadata);
+            if (!group.variants.some((existing)=>getVariantKey(existing) === getVariantKey(variant))) {
+                group.variants.push(variant);
+            }
+        }
+        for (const group of groups.values()){
+            group.variants = group.variants.toSorted((a, b)=>comparePluginVersions(b.version ?? '', a.version ?? ''));
+            group.hasMultipleVersions = new Set(group.variants.map((v)=>v.version ?? '')).size > 1;
+            group.hasMultipleRegistries = new Set(group.variants.map((v)=>v.registry ?? '')).size > 1;
+        }
+        return [
+            ...groups.values()
+        ];
+    }, [
+        sortedData
+    ]);
+    const options = useMemo(()=>kindGroups.flatMap((group)=>getGroupOptions(group, enableVersionSelection, enableRegistrySelection)), [
+        kindGroups,
+        enableVersionSelection,
+        enableRegistrySelection
+    ]);
+    const labelsByValue = useMemo(()=>new Map(options.map((option)=>[
+                option.value,
+                option.label
+            ])), [
+        options
+    ]);
     // Pass an empty value while options are still loading so MUI doesn't complain about us using an "out of range" value
-    const value = !propValue || isLoading ? '' : selectionToOptionValue(propValue);
+    const value = useMemo(()=>{
+        if (!propValue || isLoading) {
+            return '';
+        }
+        const optionValue = selectionToOptionValue(propValue);
+        if (labelsByValue.has(optionValue)) {
+            return optionValue;
+        }
+        // The definition is not pinned (or is pinned to something we don't list): fall back to the first entry of that
+        // plugin kind, which is the one that will actually be used, so the Select has a matching value.
+        const fallback = options.find((option)=>option.selection.type === propValue.type && option.selection.kind === propValue.kind);
+        return fallback?.value ?? optionValue;
+    }, [
+        propValue,
+        isLoading,
+        labelsByValue,
+        options
+    ]);
     const handleChange = (event)=>{
         onChange?.(optionValueToSelection(event.target.value));
     };
@@ -41,10 +180,16 @@ import { useListPluginMetadata } from '../../runtime';
         if (selected === '') {
             return '';
         }
-        const selectedValue = optionValueToSelection(selected);
-        return sortedData?.find((v)=>v.kind === selectedValue.type && v.spec.name === selectedValue.kind)?.spec.display.name;
+        const optionValue = selected;
+        const label = labelsByValue.get(optionValue);
+        if (label !== undefined) {
+            return label;
+        }
+        const selectedValue = optionValueToSelection(optionValue);
+        return kindGroups.find((group)=>group.type === selectedValue.type && group.kind === selectedValue.kind)?.displayName;
     }, [
-        sortedData
+        labelsByValue,
+        kindGroups
     ]);
     // TODO: Does this need a loading indicator of some kind?
     return /*#__PURE__*/ _jsxs(TextField, {
@@ -63,14 +208,11 @@ import { useListPluginMetadata } from '../../runtime';
                 value: "",
                 children: "Loading..."
             }),
-            sortedData?.map((metadata)=>/*#__PURE__*/ _jsx(MenuItem, {
+            options.map((option)=>/*#__PURE__*/ _jsx(MenuItem, {
                     "data-testid": "option",
-                    value: selectionToOptionValue({
-                        type: metadata.kind,
-                        kind: metadata.spec.name
-                    }),
-                    children: metadata.spec.display.name
-                }, metadata.kind + metadata.spec.name))
+                    value: option.value,
+                    children: option.label
+                }, option.value))
         ]
     });
 });
@@ -78,29 +220,51 @@ PluginKindSelect.displayName = 'PluginKindSelect';
 // Delimiter used to stringify/parse option values
 const OPTION_VALUE_DELIMITER = '_____';
 /**
- * Given a PluginEditorSelection,
- * returns a string value like `{type}_____{kind}` that can be used as a Select input value.
+ * Given a PluginEditorSelection, returns a string value like `{type}_____{kind}` that can be used as a Select input
+ * value. A pinned version and/or registry is appended as `{type}_____{kind}_____{version}_____{registry}`, with empty
+ * segments for the parts that are not pinned.
  * @param selector
  */ function selectionToOptionValue(selector) {
-    return [
+    const { version, registry } = selector.metadata ?? {};
+    const parts = [
         selector.type,
         selector.kind
-    ].join(OPTION_VALUE_DELIMITER);
+    ];
+    if (version || registry) {
+        parts.push(version ?? '');
+    }
+    if (registry) {
+        parts.push(registry);
+    }
+    return parts.join(OPTION_VALUE_DELIMITER);
 }
 /**
- * Given an option value name like `{type}_____{kind}`,
- * returns a PluginEditorSelection to be used by the query data model.
+ * Given an option value name like `{type}_____{kind}` or `{type}_____{kind}_____{version}_____{registry}`, returns a
+ * PluginEditorSelection to be used by the query data model.
  * @param optionValue
  */ function optionValueToSelection(optionValue) {
     const words = optionValue.split(OPTION_VALUE_DELIMITER);
     const type = words[0];
     const kind = words[1];
+    const version = words[2];
+    const registry = words[3];
     if (type === undefined || kind === undefined) {
         throw new Error('Invalid optionValue string');
     }
+    const metadata = {
+        ...version ? {
+            version
+        } : {},
+        ...registry ? {
+            registry
+        } : {}
+    };
     return {
         type,
-        kind
+        kind,
+        ...version || registry ? {
+            metadata
+        } : {}
     };
 }
 

package/dist/components/PluginKindSelect/PluginKindSelect.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/PluginKindSelect/PluginKindSelect.tsx"],"sourcesContent":["// Copyright The Perses Authors\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nimport { MenuItem, TextField, TextFieldProps } from '@mui/material';\nimport { forwardRef, ReactElement, useCallback, useMemo } from 'react';\nimport { PluginType } from '../../model';\nimport { useListPluginMetadata } from '../../runtime';\nimport { PluginEditorSelection } from '../PluginEditor';\n\nexport interface PluginKindSelectProps extends Omit<TextFieldProps, 'value' | 'onChange' | 'children'> {\n  filteredQueryPlugins?: string[];\n  pluginTypes: PluginType[];\n  value?: PluginEditorSelection;\n  onChange?: (s: PluginEditorSelection) => void;\n}\n\n/**\n * Displays a MUI Select input for selecting a plugin's kind from a list of all the available plugins of some specific\n * plugin types. (e.g. \"Show a list of all the Panel plugins\", or \"Show a list of all the Variable plugins\", or \"Show\n * a list of all the TimeSeriesQuery, TraceQuery, ProfileQuery, and LogQuery plugins\").\n * The value of the select is the kind of the plugin, but you can also listen to the `onPluginTypeChange` event to know\n * when the user changes the plugin type (it fires at start for the default value.)\n */\nexport const PluginKindSelect = forwardRef((props: PluginKindSelectProps, ref): ReactElement => {\n  const { pluginTypes, value: propValue, onChange, filteredQueryPlugins, ...others } = props;\n  const { data, isLoading } = useListPluginMetadata(pluginTypes);\n\n  const sortedData = useMemo(() => {\n    if (filteredQueryPlugins?.length) {\n      return data\n        ?.filter((i) => filteredQueryPlugins.includes(i.spec.name))\n        ?.sort((a, b) => a.spec.display.name.localeCompare(b.spec.display.name));\n    }\n\n    return data?.sort((a, b) => a.spec.display.name.localeCompare(b.spec.display.name));\n  }, [data, filteredQueryPlugins]);\n\n  // Pass an empty value while options are still loading so MUI doesn't complain about us using an \"out of range\" value\n  const value = !propValue || isLoading ? '' : selectionToOptionValue(propValue);\n\n  const handleChange = (event: { target: { value: string } }): void => {\n    onChange?.(optionValueToSelection(event.target.value));\n  };\n\n  const renderValue = useCallback(\n    (selected: unknown) => {\n      if (selected === '') {\n        return '';\n      }\n      const selectedValue = optionValueToSelection(selected as string);\n      return sortedData?.find((v) => v.kind === selectedValue.type && v.spec.name === selectedValue.kind)?.spec.display\n        .name;\n    },\n    [sortedData]\n  );\n\n  // TODO: Does this need a loading indicator of some kind?\n  return (\n    <TextField\n      select\n      inputRef={ref}\n      {...others}\n      value={value}\n      aria-label={value}\n      onChange={handleChange}\n      SelectProps={{ renderValue }}\n      data-testid=\"plugin-kind-select\"\n    >\n      {isLoading && <MenuItem value=\"\">Loading...</MenuItem>}\n      {sortedData?.map((metadata) => (\n        <MenuItem\n          data-testid=\"option\"\n          key={metadata.kind + metadata.spec.name}\n          value={selectionToOptionValue({ type: metadata.kind, kind: metadata.spec.name })}\n        >\n          {metadata.spec.display.name}\n        </MenuItem>\n      ))}\n    </TextField>\n  );\n});\nPluginKindSelect.displayName = 'PluginKindSelect';\n\n// Delimiter used to stringify/parse option values\nconst OPTION_VALUE_DELIMITER = '_____';\n\n/**\n * Given a PluginEditorSelection,\n * returns a string value like `{type}_____{kind}` that can be used as a Select input value.\n * @param selector\n */\nfunction selectionToOptionValue(selector: PluginEditorSelection): string {\n  return [selector.type, selector.kind].join(OPTION_VALUE_DELIMITER);\n}\n\n/**\n * Given an option value name like `{type}_____{kind}`,\n * returns a PluginEditorSelection to be used by the query data model.\n * @param optionValue\n */\nfunction optionValueToSelection(optionValue: string): PluginEditorSelection {\n  const words = optionValue.split(OPTION_VALUE_DELIMITER);\n  const type = words[0] as PluginType | undefined;\n  const kind = words[1];\n  if (type === undefined || kind === undefined) {\n    throw new Error('Invalid optionValue string');\n  }\n  return {\n    type,\n    kind,\n  };\n}\n"],"names":["MenuItem","TextField","forwardRef","useCallback","useMemo","useListPluginMetadata","PluginKindSelect","props","ref","pluginTypes","value","propValue","onChange","filteredQueryPlugins","others","data","isLoading","sortedData","length","filter","i","includes","spec","name","sort","a","b","display","localeCompare","selectionToOptionValue","handleChange","event","optionValueToSelection","target","renderValue","selected","selectedValue","find","v","kind","type","select","inputRef","aria-label","SelectProps","data-testid","map","metadata","displayName","OPTION_VALUE_DELIMITER","selector","join","optionValue","words","split","undefined","Error"],"mappings":"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"}
+{"version":3,"sources":["../../../src/components/PluginKindSelect/PluginKindSelect.tsx"],"sourcesContent":["// Copyright The Perses Authors\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nimport type { TextFieldProps } from '@mui/material';\nimport { MenuItem, TextField } from '@mui/material';\nimport type { PluginDefinitionMetadata } from '@perses-dev/spec';\nimport type { ReactElement } from 'react';\nimport { forwardRef, useCallback, useMemo } from 'react';\n\nimport type { PluginMetadataWithModule, PluginType } from '../../model';\nimport { useListPluginMetadata } from '../../runtime';\nimport { comparePluginVersions } from '../../utils';\nimport type { PluginEditorSelection } from '../PluginEditor';\n\nexport interface PluginKindSelectProps extends Omit<TextFieldProps, 'value' | 'onChange' | 'children'> {\n  filteredQueryPlugins?: string[];\n  pluginTypes: PluginType[];\n  value?: PluginEditorSelection;\n  onChange?: (s: PluginEditorSelection) => void;\n  /**\n   * When true, a plugin that has more than one version available is listed with a `<display name> - Latest` option and\n   * once per version, labeled `<display name> - <version>`. Selecting a specific version sets `metadata.version` on the\n   * selection so it can be persisted on the definition, while selecting Latest leaves the version unpinned. A plugin\n   * with a single available version is listed without a version, so it keeps resolving to the latest one. Defaults to\n   * false.\n   */\n  enableVersionSelection?: boolean;\n  /**\n   * When true, a plugin that is available in more than one registry is listed once per registry, labeled\n   * `<display name> (<registry>)`. Selecting such an option sets `metadata.registry` on the selection. A plugin\n   * available in a single registry is listed without it. Defaults to false.\n   */\n  enableRegistrySelection?: boolean;\n}\n\n/** A plugin kind grouped with all of the variants it is installed under. */\ninterface PluginKindGroup {\n  type: PluginType;\n  kind: string;\n  displayName: string;\n  /** Available variants, sorted from the newest version to the oldest. */\n  variants: PluginDefinitionMetadata[];\n  hasMultipleVersions: boolean;\n  hasMultipleRegistries: boolean;\n}\n\n/** A selectable entry of the select input. */\ninterface PluginKindOption {\n  selection: PluginEditorSelection;\n  label: string;\n  /** Stringified `selection`, used as the MUI Select option value. */\n  value: string;\n}\n\nfunction getVariant(metadata: PluginMetadataWithModule): PluginDefinitionMetadata {\n  return {\n    version: metadata.metadata?.version ?? metadata.module?.version,\n    registry: metadata.metadata?.registry ?? metadata.module?.registry,\n  };\n}\n\nfunction getVariantKey(variant: PluginDefinitionMetadata): string {\n  return `${variant.version ?? ''}:${variant.registry ?? ''}`;\n}\n\n/**\n * Build the selectable entries of a plugin kind. A version (resp. registry) is only part of the entries when the caller\n * enabled its selection *and* the plugin is actually installed in more than one version (resp. registry): there is\n * nothing to pick otherwise, and leaving it out keeps the definition floating on the latest version.\n */\nfunction getGroupOptions(\n  group: PluginKindGroup,\n  enableVersionSelection: boolean,\n  enableRegistrySelection: boolean,\n): PluginKindOption[] {\n  const showVersion = enableVersionSelection && group.hasMultipleVersions;\n  const showRegistry = enableRegistrySelection && group.hasMultipleRegistries;\n\n  if (!showVersion && !showRegistry) {\n    const selection: PluginEditorSelection = { type: group.type, kind: group.kind };\n    return [{ selection, label: group.displayName, value: selectionToOptionValue(selection) }];\n  }\n\n  const options: PluginKindOption[] = [];\n  const seen = new Set<string>();\n  if (showVersion) {\n    const selection: PluginEditorSelection = { type: group.type, kind: group.kind };\n    options.push({\n      selection,\n      label: `${group.displayName} - Latest`,\n      value: selectionToOptionValue(selection),\n    });\n    seen.add(getVariantKey({}));\n  }\n  for (const variant of group.variants) {\n    const version = showVersion ? variant.version : undefined;\n    const registry = showRegistry ? variant.registry : undefined;\n    const metadata: PluginDefinitionMetadata = {\n      ...(version ? { version } : {}),\n      ...(registry ? { registry } : {}),\n    };\n    // Variants that only differ on a field we don't display collapse into a single entry.\n    const key = getVariantKey({ version, registry });\n    if (seen.has(key)) {\n      continue;\n    }\n    seen.add(key);\n\n    const selection: PluginEditorSelection = {\n      type: group.type,\n      kind: group.kind,\n      ...(version || registry ? { metadata } : {}),\n    };\n    const label = `${group.displayName}${version ? ` - ${version}` : ''}${registry ? ` (${registry})` : ''}`;\n    options.push({ selection, label, value: selectionToOptionValue(selection) });\n  }\n  return options;\n}\n\n/**\n * Displays a MUI Select input for selecting a plugin's kind from a list of all the available plugins of some specific\n * plugin types. (e.g. \"Show a list of all the Panel plugins\", or \"Show a list of all the Variable plugins\", or \"Show\n * a list of all the TimeSeriesQuery, TraceQuery, ProfileQuery, and LogQuery plugins\").\n * The value of the select is the kind of the plugin, but you can also listen to the `onPluginTypeChange` event to know\n * when the user changes the plugin type (it fires at start for the default value.)\n */\nexport const PluginKindSelect = forwardRef((props: PluginKindSelectProps, ref): ReactElement => {\n  const {\n    pluginTypes,\n    value: propValue,\n    onChange,\n    filteredQueryPlugins,\n    enableVersionSelection = false,\n    enableRegistrySelection = false,\n    ...others\n  } = props;\n  const { data, isLoading } = useListPluginMetadata(pluginTypes);\n\n  const sortedData = useMemo(() => {\n    const filtered = filteredQueryPlugins?.length\n      ? data?.filter((i) => filteredQueryPlugins.includes(i.spec.name))\n      : data;\n    return filtered?.toSorted((a, b) => a.spec.display.name.localeCompare(b.spec.display.name));\n  }, [data, filteredQueryPlugins]);\n\n  // Group the metadata by plugin kind, collecting all the variants each one is installed under (newest version first).\n  const kindGroups = useMemo<PluginKindGroup[]>(() => {\n    const groups = new Map<string, PluginKindGroup>();\n    for (const metadata of sortedData ?? []) {\n      const key = `${metadata.kind}:${metadata.spec.name}`;\n      let group = groups.get(key);\n      if (group === undefined) {\n        group = {\n          type: metadata.kind,\n          kind: metadata.spec.name,\n          displayName: metadata.spec.display.name,\n          variants: [],\n          hasMultipleVersions: false,\n          hasMultipleRegistries: false,\n        };\n        groups.set(key, group);\n      }\n      const variant = getVariant(metadata);\n      if (!group.variants.some((existing) => getVariantKey(existing) === getVariantKey(variant))) {\n        group.variants.push(variant);\n      }\n    }\n    for (const group of groups.values()) {\n      group.variants = group.variants.toSorted((a, b) => comparePluginVersions(b.version ?? '', a.version ?? ''));\n      group.hasMultipleVersions = new Set(group.variants.map((v) => v.version ?? '')).size > 1;\n      group.hasMultipleRegistries = new Set(group.variants.map((v) => v.registry ?? '')).size > 1;\n    }\n    return [...groups.values()];\n  }, [sortedData]);\n\n  const options = useMemo(\n    () => kindGroups.flatMap((group) => getGroupOptions(group, enableVersionSelection, enableRegistrySelection)),\n    [kindGroups, enableVersionSelection, enableRegistrySelection],\n  );\n\n  const labelsByValue = useMemo(() => new Map(options.map((option) => [option.value, option.label])), [options]);\n\n  // Pass an empty value while options are still loading so MUI doesn't complain about us using an \"out of range\" value\n  const value = useMemo(() => {\n    if (!propValue || isLoading) {\n      return '';\n    }\n    const optionValue = selectionToOptionValue(propValue);\n    if (labelsByValue.has(optionValue)) {\n      return optionValue;\n    }\n    // The definition is not pinned (or is pinned to something we don't list): fall back to the first entry of that\n    // plugin kind, which is the one that will actually be used, so the Select has a matching value.\n    const fallback = options.find(\n      (option) => option.selection.type === propValue.type && option.selection.kind === propValue.kind,\n    );\n    return fallback?.value ?? optionValue;\n  }, [propValue, isLoading, labelsByValue, options]);\n\n  const handleChange = (event: { target: { value: string } }): void => {\n    onChange?.(optionValueToSelection(event.target.value));\n  };\n\n  const renderValue = useCallback(\n    (selected: unknown) => {\n      if (selected === '') {\n        return '';\n      }\n      const optionValue = selected as string;\n      const label = labelsByValue.get(optionValue);\n      if (label !== undefined) {\n        return label;\n      }\n      const selectedValue = optionValueToSelection(optionValue);\n      return kindGroups.find((group) => group.type === selectedValue.type && group.kind === selectedValue.kind)\n        ?.displayName;\n    },\n    [labelsByValue, kindGroups],\n  );\n\n  // TODO: Does this need a loading indicator of some kind?\n  return (\n    <TextField\n      select\n      inputRef={ref}\n      {...others}\n      value={value}\n      aria-label={value}\n      onChange={handleChange}\n      SelectProps={{ renderValue }}\n      data-testid=\"plugin-kind-select\"\n    >\n      {isLoading && <MenuItem value=\"\">Loading...</MenuItem>}\n      {options.map((option) => (\n        <MenuItem data-testid=\"option\" key={option.value} value={option.value}>\n          {option.label}\n        </MenuItem>\n      ))}\n    </TextField>\n  );\n});\nPluginKindSelect.displayName = 'PluginKindSelect';\n\n// Delimiter used to stringify/parse option values\nconst OPTION_VALUE_DELIMITER = '_____';\n\n/**\n * Given a PluginEditorSelection, returns a string value like `{type}_____{kind}` that can be used as a Select input\n * value. A pinned version and/or registry is appended as `{type}_____{kind}_____{version}_____{registry}`, with empty\n * segments for the parts that are not pinned.\n * @param selector\n */\nfunction selectionToOptionValue(selector: PluginEditorSelection): string {\n  const { version, registry } = selector.metadata ?? {};\n  const parts = [selector.type, selector.kind];\n  if (version || registry) {\n    parts.push(version ?? '');\n  }\n  if (registry) {\n    parts.push(registry);\n  }\n  return parts.join(OPTION_VALUE_DELIMITER);\n}\n\n/**\n * Given an option value name like `{type}_____{kind}` or `{type}_____{kind}_____{version}_____{registry}`, returns a\n * PluginEditorSelection to be used by the query data model.\n * @param optionValue\n */\nfunction optionValueToSelection(optionValue: string): PluginEditorSelection {\n  const words = optionValue.split(OPTION_VALUE_DELIMITER);\n  const type = words[0] as PluginType | undefined;\n  const kind = words[1];\n  const version = words[2];\n  const registry = words[3];\n  if (type === undefined || kind === undefined) {\n    throw new Error('Invalid optionValue string');\n  }\n  const metadata: PluginDefinitionMetadata = {\n    ...(version ? { version } : {}),\n    ...(registry ? { registry } : {}),\n  };\n  return {\n    type,\n    kind,\n    ...(version || registry ? { metadata } : {}),\n  };\n}\n"],"names":["MenuItem","TextField","forwardRef","useCallback","useMemo","useListPluginMetadata","comparePluginVersions","getVariant","metadata","version","module","registry","getVariantKey","variant","getGroupOptions","group","enableVersionSelection","enableRegistrySelection","showVersion","hasMultipleVersions","showRegistry","hasMultipleRegistries","selection","type","kind","label","displayName","value","selectionToOptionValue","options","seen","Set","push","add","variants","undefined","key","has","PluginKindSelect","props","ref","pluginTypes","propValue","onChange","filteredQueryPlugins","others","data","isLoading","sortedData","filtered","length","filter","i","includes","spec","name","toSorted","a","b","display","localeCompare","kindGroups","groups","Map","get","set","some","existing","values","map","v","size","flatMap","labelsByValue","option","optionValue","fallback","find","handleChange","event","optionValueToSelection","target","renderValue","selected","selectedValue","select","inputRef","aria-label","SelectProps","data-testid","OPTION_VALUE_DELIMITER","selector","parts","join","words","split","Error"],"mappings":"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"}

package/dist/components/PluginKindSelect/index.js

@@ -10,6 +10,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-export * from './PluginKindSelect';
+export * from "./PluginKindSelect.js";
 
 //# sourceMappingURL=index.js.map

package/dist/components/PluginKindSelect/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/PluginKindSelect/index.tsx"],"sourcesContent":["// Copyright The Perses Authors\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nexport * from './PluginKindSelect';\n"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,6CAA6C;AAC7C,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AAEjC,cAAc,qBAAqB"}
+{"version":3,"sources":["../../../src/components/PluginKindSelect/index.tsx"],"sourcesContent":["// Copyright The Perses Authors\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nexport * from './PluginKindSelect';\n"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,6CAA6C;AAC7C,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AAEjC,cAAc,wBAAqB"}

package/dist/components/PluginRegistry/PluginRegistry.d.ts

@@ -1,5 +1,5 @@
-import { ReactNode, ReactElement } from 'react';
-import { PluginLoader, DefaultPluginKinds } from '../../model';
+import type { ReactNode, ReactElement } from 'react';
+import type { PluginLoader, DefaultPluginKinds } from '../../model';
 export interface PluginRegistryProps {
     pluginLoader: PluginLoader;
     defaultPluginKinds?: DefaultPluginKinds;

package/dist/components/PluginRegistry/PluginRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PluginRegistry.d.ts","sourceRoot":"","sources":["../../../src/components/PluginRegistry/PluginRegistry.tsx"],"names":[],"mappings":"AAcA,OAAO,EAAgC,SAAS,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC9E,OAAO,EAKL,YAAY,EACZ,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,YAAY,CAoEvE"}
+{"version":3,"file":"PluginRegistry.d.ts","sourceRoot":"","sources":["../../../src/components/PluginRegistry/PluginRegistry.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAGrD,OAAO,KAAK,EAKV,YAAY,EACZ,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAOrB,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA2CD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,YAAY,CA4FvE"}

package/dist/components/PluginRegistry/PluginRegistry.js

@@ -11,11 +11,46 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useRef, useCallback, useMemo } from 'react';
-import { PluginRegistryContext } from '../../runtime';
-import { useEvent } from '../../utils';
-import { usePluginIndexes } from './plugin-indexes';
-import { resolvePluginKeys } from './getPluginSearchHelper';
+import { useRef, useCallback, useMemo } from "react";
+import { PluginRegistryContext } from "../../runtime/index.js";
+import { comparePluginVersions, useEvent } from "../../utils/index.js";
+import { resolvePluginKeys } from "./getPluginSearchHelper.js";
+import { usePluginIndexes } from "./plugin-indexes.js";
+/**
+ * Returns the indexed key of a plugin served by a local dev server for the given plugin type and kind, if any.
+ * Keys are `${kind}:${name}:${registry}:${version}`, so we match on the `kind:name:` prefix.
+ */ function findDevPluginKey(devPluginKeys, kind, name) {
+    const prefix = `${kind}:${name}:`;
+    for (const key of devPluginKeys){
+        if (key.startsWith(prefix)) {
+            return key;
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the indexed keys (`${kind}:${name}:${registry}:${version}`) matching *every* field supplied in the query.
+ * `kind` and `name` are always compared; `registry` and `version` are only compared when they are set, so a
+ * version-only pin matches whatever registry the plugin happens to be installed under, and a registry-only pin never
+ * leaks into another registry. Results are ordered from the newest version to the oldest.
+ */ function findMatchingPluginKeys(allKeys, query) {
+    const { kind, name, registry, version } = query;
+    const prefix = `${kind}:${name}:`;
+    const matches = [];
+    for (const key of allKeys){
+        if (!key.startsWith(prefix)) continue;
+        const parts = key.split(':');
+        if (parts.length !== 4) continue;
+        const [, , keyRegistry, keyVersion] = parts;
+        if (registry !== undefined && keyRegistry !== registry) continue;
+        if (version !== undefined && keyVersion !== version) continue;
+        matches.push({
+            key,
+            version: keyVersion ?? ''
+        });
+    }
+    return matches.toSorted((a, b)=>comparePluginVersions(b.version, a.version)).map((match)=>match.key);
+}
 /**
  * PluginRegistryContext provider that keeps track of all available plugins and provides an API for getting them or
  * querying the metadata about them.
@@ -38,8 +73,26 @@ import { resolvePluginKeys } from './getPluginSearchHelper';
     });
     const getPlugin = useCallback(async (compoundKeyObj)=>{
         const pluginIndexes = await getPluginIndexes();
-        const { kind, name } = compoundKeyObj;
-        const candidateKeys = resolvePluginKeys(pluginIndexes.pluginResourcesByNameKindRegistryVersion.keys(), compoundKeyObj);
+        const { kind, name, version, registry } = compoundKeyObj;
+        const allKeys = pluginIndexes.pluginResourcesByNameKindRegistryVersion.keys();
+        let candidateKeys;
+        if (version || registry) {
+            // A pin is an exact constraint: only the plugins matching every supplied field are acceptable, and we never
+            // silently fall back to another version or another registry.
+            candidateKeys = findMatchingPluginKeys(allKeys, compoundKeyObj);
+        } else {
+            candidateKeys = resolvePluginKeys(allKeys, compoundKeyObj);
+            // Nothing pinned: a plugin served by a local dev server (`percli plugin start`) wins over installed archives,
+            // whatever their versions. Otherwise a dev plugin whose package version is lower than an installed archive would
+            // never be used, which defeats the purpose of running it in dev.
+            const devKey = findDevPluginKey(pluginIndexes.devPluginKeys, kind, name);
+            if (devKey) {
+                candidateKeys = [
+                    devKey,
+                    ...candidateKeys.filter((key)=>key !== devKey)
+                ];
+            }
+        }
         for (const resourceKey of candidateKeys){
             const resource = pluginIndexes.pluginResourcesByNameKindRegistryVersion.get(resourceKey);
             if (!resource) continue;
@@ -51,13 +104,23 @@ import { resolvePluginKeys } from './getPluginSearchHelper';
             const versionlessPlugin = pluginModule?.[name];
             if (versionlessPlugin) return versionlessPlugin;
         }
-        throw new Error(`A ${name} plugin for kind '${kind}' is not installed`);
+        const pins = [
+            version ? `version '${version}'` : undefined,
+            registry ? `registry '${registry}'` : undefined
+        ].filter((pin)=>pin !== undefined);
+        throw new Error(pins.length > 0 ? `A ${name} plugin for kind '${kind}' with ${pins.join(' and ')} is not installed` : `A ${name} plugin for kind '${kind}' is not installed`);
     }, [
         getPluginIndexes,
         loadPluginModule
     ]);
     const listPluginMetadata = useCallback(async (pluginTypes)=>{
         const pluginIndexes = await getPluginIndexes();
+        if (pluginTypes === undefined) {
+            // No filter: return the metadata of every installed plugin, whatever its type.
+            return [
+                ...pluginIndexes.pluginMetadataByKind.values()
+            ].flat();
+        }
         return pluginTypes.flatMap((type)=>pluginIndexes.pluginMetadataByKind.get(type) ?? []);
     }, [
         getPluginIndexes