deprecate LocalStoredShortcuts, add DefaultShortcutsApi

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/six-mails-shout.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-shortcuts': patch
+---
+
+Marked `LocalStoredShortcuts` as deprecated, replacing it with `DefaultShortcutsApi` whose naming more clearly suggests that the shortcuts aren't necessarily stored locally (it depends on the storage implementation).

plugins/shortcuts/api-report.md

@@ -14,7 +14,7 @@ import { ShortcutApi as ShortcutApi_2 } from '@backstage/plugin-shortcuts';
 import type { StorageApi } from '@backstage/core-plugin-api';
 
 // @public
-export class LocalStoredShortcuts implements ShortcutApi_2 {
+export class DefaultShortcutsApi implements ShortcutApi_2 {
   constructor(storageApi: StorageApi);
   // (undocumented)
   add(shortcut: Omit<Shortcut_2, 'id'>): Promise<void>;
@@ -30,6 +30,9 @@ export class LocalStoredShortcuts implements ShortcutApi_2 {
   update(shortcut: Shortcut_2): Promise<void>;
 }
 
+// @public @deprecated (undocumented)
+export const LocalStoredShortcuts: typeof DefaultShortcutsApi;
+
 // @public (undocumented)
 export type Shortcut = {
   id: string;

plugins/shortcuts/src/AddShortcut.test.tsx

@@ -17,7 +17,7 @@
 import React from 'react';
 import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { AddShortcut } from './AddShortcut';
-import { LocalStoredShortcuts } from './api';
+import { DefaultShortcutsApi } from './api';
 import {
   MockAnalyticsApi,
   MockStorageApi,
@@ -28,7 +28,7 @@ import { TestApiProvider } from '@backstage/test-utils';
 import { analyticsApiRef } from '@backstage/core-plugin-api';
 
 describe('AddShortcut', () => {
-  const api = new LocalStoredShortcuts(MockStorageApi.create());
+  const api = new DefaultShortcutsApi(MockStorageApi.create());
 
   const props = {
     onClose: jest.fn(),

plugins/shortcuts/src/EditShortcut.test.tsx

@@ -18,7 +18,7 @@ import React from 'react';
 import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { EditShortcut } from './EditShortcut';
 import { Shortcut } from './types';
-import { LocalStoredShortcuts } from './api';
+import { DefaultShortcutsApi } from './api';
 import {
   MockAnalyticsApi,
   MockStorageApi,
@@ -34,7 +34,7 @@ describe('EditShortcut', () => {
     url: '/some-url',
     title: 'some title',
   };
-  const api = new LocalStoredShortcuts(MockStorageApi.create());
+  const api = new DefaultShortcutsApi(MockStorageApi.create());
 
   const props = {
     onClose: jest.fn(),

plugins/shortcuts/src/ShortcutItem.test.tsx

@@ -18,7 +18,7 @@ import React from 'react';
 import { screen, waitFor } from '@testing-library/react';
 import { ShortcutItem } from './ShortcutItem';
 import { Shortcut } from './types';
-import { LocalStoredShortcuts } from './api';
+import { DefaultShortcutsApi } from './api';
 import { MockStorageApi, renderInTestApp } from '@backstage/test-utils';
 import { SidebarOpenStateProvider } from '@backstage/core-components';
 
@@ -28,7 +28,7 @@ describe('ShortcutItem', () => {
     url: '/some-url',
     title: 'some title',
   };
-  const api = new LocalStoredShortcuts(MockStorageApi.create());
+  const api = new DefaultShortcutsApi(MockStorageApi.create());
 
   it('displays the shortcut', async () => {
     await renderInTestApp(

plugins/shortcuts/src/Shortcuts.test.tsx

@@ -22,7 +22,7 @@ import {
 } from '@backstage/test-utils';
 import { screen, waitFor } from '@testing-library/react';
 import { Shortcuts } from './Shortcuts';
-import { LocalStoredShortcuts, shortcutsApiRef } from './api';
+import { DefaultShortcutsApi, shortcutsApiRef } from './api';
 
 import { SidebarOpenStateProvider } from '@backstage/core-components';
 
@@ -32,10 +32,7 @@ describe('Shortcuts', () => {
       <SidebarOpenStateProvider value={{ isOpen: true, setOpen: _open => {} }}>
         <TestApiProvider
           apis={[
-            [
-              shortcutsApiRef,
-              new LocalStoredShortcuts(MockStorageApi.create()),
-            ],
+            [shortcutsApiRef, new DefaultShortcutsApi(MockStorageApi.create())],
           ]}
         >
           <Shortcuts />

plugins/shortcuts/src/api/DefaultShortcutsApi.test.ts

@@ -17,12 +17,12 @@
 import { MockStorageApi } from '@backstage/test-utils';
 import { pageTheme } from '@backstage/theme';
 import { Shortcut } from '../types';
-import { LocalStoredShortcuts } from './LocalStoredShortcuts';
+import { DefaultShortcutsApi } from './DefaultShortcutsApi';
 import { ShortcutApi } from './ShortcutApi';
 
-describe('LocalStoredShortcuts', () => {
+describe('DefaultShortcutsApi', () => {
   it('should observe shortcuts', async () => {
-    const shortcutApi: ShortcutApi = new LocalStoredShortcuts(
+    const shortcutApi: ShortcutApi = new DefaultShortcutsApi(
       MockStorageApi.create(),
     );
     const shortcut: Shortcut = { id: 'id', title: 'title', url: '/url' };
@@ -48,7 +48,7 @@ describe('LocalStoredShortcuts', () => {
 
   it('should add shortcuts with ids', async () => {
     const storageApi = MockStorageApi.create();
-    const shortcutApi: ShortcutApi = new LocalStoredShortcuts(storageApi);
+    const shortcutApi: ShortcutApi = new DefaultShortcutsApi(storageApi);
     const shortcut: Omit<Shortcut, 'id'> = { title: 'title', url: '/url' };
     const spy = jest.spyOn(storageApi, 'set');
 
@@ -61,7 +61,7 @@ describe('LocalStoredShortcuts', () => {
 
   it('should update shortcuts', async () => {
     const storageApi = MockStorageApi.create();
-    const shortcutApi: ShortcutApi = new LocalStoredShortcuts(storageApi);
+    const shortcutApi: ShortcutApi = new DefaultShortcutsApi(storageApi);
     const shortcut: Shortcut = { id: 'someid', title: 'title', url: '/url' };
     const spy = jest.spyOn(storageApi, 'set');
 
@@ -74,7 +74,7 @@ describe('LocalStoredShortcuts', () => {
 
   it('should remove shortcuts', async () => {
     const storageApi = MockStorageApi.create();
-    const shortcutApi: ShortcutApi = new LocalStoredShortcuts(storageApi);
+    const shortcutApi: ShortcutApi = new DefaultShortcutsApi(storageApi);
     const shortcut: Shortcut = { id: 'someid', title: 'title', url: '/url' };
     const spy = jest.spyOn(storageApi, 'set');
 
@@ -84,7 +84,7 @@ describe('LocalStoredShortcuts', () => {
 
   it('should get a color', () => {
     const storageApi = MockStorageApi.create();
-    const shortcutApi: ShortcutApi = new LocalStoredShortcuts(storageApi);
+    const shortcutApi: ShortcutApi = new DefaultShortcutsApi(storageApi);
 
     expect(shortcutApi.getColor('/catalog')).toEqual(pageTheme.home.colors[0]);
   });

plugins/shortcuts/src/api/DefaultShortcutsApi.ts

@@ -22,11 +22,18 @@ import type { Observable } from '@backstage/types';
 import ObservableImpl from 'zen-observable';
 
 /**
- * Implementation of the ShortcutApi that uses the StorageApi to store shortcuts.
+ * Default implementation of the {@link ShortcutApi} that uses the
+ * {@link @backstage/core-plugin-api#StorageApi} to store shortcuts.
+ *
+ * @remarks
+ *
+ * Note that the storage API given is used directly, as in, this implementation
+ * does not itself dive into a sub-bucket. So you may want to provide a bucket
+ * that is scoped to the plugin (default: 'shortcuts').
  *
  * @public
  */
-export class LocalStoredShortcuts implements ShortcutApi {
+export class DefaultShortcutsApi implements ShortcutApi {
   private shortcuts: Shortcut[];
   private readonly subscribers = new Set<
     ZenObservable.SubscriptionObserver<Shortcut[]>

plugins/shortcuts/src/api/index.ts

@@ -14,6 +14,6 @@
  * limitations under the License.
  */
 
-export { LocalStoredShortcuts } from './LocalStoredShortcuts';
+export { DefaultShortcutsApi } from './DefaultShortcutsApi';
 export { shortcutsApiRef } from './ShortcutApi';
 export type { ShortcutApi } from './ShortcutApi';

plugins/shortcuts/src/deprecated.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * 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 { DefaultShortcutsApi } from './api';
+
+/**
+ * @public
+ * @deprecated Use {@link DefaultShortcutsApi} instead.
+ */
+export const LocalStoredShortcuts = DefaultShortcutsApi;

plugins/shortcuts/src/index.ts

@@ -22,5 +22,6 @@
 
 export { shortcutsPlugin, Shortcuts } from './plugin';
 export * from './api';
+export * from './deprecated';
 export type { Shortcut } from './types';
 export type { ShortcutsProps } from './Shortcuts';

plugins/shortcuts/src/plugin.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { LocalStoredShortcuts, shortcutsApiRef } from './api';
+import { DefaultShortcutsApi, shortcutsApiRef } from './api';
 import {
   createApiFactory,
   createComponentExtension,
@@ -30,7 +30,7 @@ export const shortcutsPlugin = createPlugin({
       api: shortcutsApiRef,
       deps: { storageApi: storageApiRef },
       factory: ({ storageApi }) =>
-        new LocalStoredShortcuts(storageApi.forBucket('shortcuts')),
+        new DefaultShortcutsApi(storageApi.forBucket('shortcuts')),
     }),
   ],
 });

plugins/shortcuts/src/setupTests.ts

@@ -13,5 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 import '@testing-library/jest-dom';
 import 'cross-fetch/polyfill';