diff --git a/.changeset/six-mails-shout.md b/.changeset/six-mails-shout.md new file mode 100644 index 0000000000..f803e0858e --- /dev/null +++ b/.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). diff --git a/plugins/shortcuts/api-report.md b/plugins/shortcuts/api-report.md index 0dd42f5344..471af42374 100644 --- a/plugins/shortcuts/api-report.md +++ b/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): Promise; @@ -30,6 +30,9 @@ export class LocalStoredShortcuts implements ShortcutApi_2 { update(shortcut: Shortcut_2): Promise; } +// @public @deprecated (undocumented) +export const LocalStoredShortcuts: typeof DefaultShortcutsApi; + // @public (undocumented) export type Shortcut = { id: string; diff --git a/plugins/shortcuts/src/AddShortcut.test.tsx b/plugins/shortcuts/src/AddShortcut.test.tsx index a697e02e99..f8786e2b24 100644 --- a/plugins/shortcuts/src/AddShortcut.test.tsx +++ b/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(), diff --git a/plugins/shortcuts/src/EditShortcut.test.tsx b/plugins/shortcuts/src/EditShortcut.test.tsx index df2ed112ba..72a89c13b6 100644 --- a/plugins/shortcuts/src/EditShortcut.test.tsx +++ b/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(), diff --git a/plugins/shortcuts/src/ShortcutItem.test.tsx b/plugins/shortcuts/src/ShortcutItem.test.tsx index b98dd2dc0b..b78b72e9cb 100644 --- a/plugins/shortcuts/src/ShortcutItem.test.tsx +++ b/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( diff --git a/plugins/shortcuts/src/Shortcuts.test.tsx b/plugins/shortcuts/src/Shortcuts.test.tsx index 02b351d3a4..a1339083b6 100644 --- a/plugins/shortcuts/src/Shortcuts.test.tsx +++ b/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', () => { {} }}> diff --git a/plugins/shortcuts/src/api/LocalStoredShortcuts.test.ts b/plugins/shortcuts/src/api/DefaultShortcutsApi.test.ts similarity index 85% rename from plugins/shortcuts/src/api/LocalStoredShortcuts.test.ts rename to plugins/shortcuts/src/api/DefaultShortcutsApi.test.ts index 86890fc75b..44bc99fb98 100644 --- a/plugins/shortcuts/src/api/LocalStoredShortcuts.test.ts +++ b/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 = { 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]); }); diff --git a/plugins/shortcuts/src/api/LocalStoredShortcuts.ts b/plugins/shortcuts/src/api/DefaultShortcutsApi.ts similarity index 87% rename from plugins/shortcuts/src/api/LocalStoredShortcuts.ts rename to plugins/shortcuts/src/api/DefaultShortcutsApi.ts index 44f7364f69..8e5fd99540 100644 --- a/plugins/shortcuts/src/api/LocalStoredShortcuts.ts +++ b/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 diff --git a/plugins/shortcuts/src/api/index.ts b/plugins/shortcuts/src/api/index.ts index eb24bed1d3..ae975208a0 100644 --- a/plugins/shortcuts/src/api/index.ts +++ b/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'; diff --git a/plugins/shortcuts/src/deprecated.ts b/plugins/shortcuts/src/deprecated.ts new file mode 100644 index 0000000000..8d5a2463fd --- /dev/null +++ b/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; diff --git a/plugins/shortcuts/src/index.ts b/plugins/shortcuts/src/index.ts index b47c94b7b1..1d35cc2721 100644 --- a/plugins/shortcuts/src/index.ts +++ b/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'; diff --git a/plugins/shortcuts/src/plugin.ts b/plugins/shortcuts/src/plugin.ts index 2b0d0559e0..8288c4fb87 100644 --- a/plugins/shortcuts/src/plugin.ts +++ b/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')), }), ], }); diff --git a/plugins/shortcuts/src/setupTests.ts b/plugins/shortcuts/src/setupTests.ts index fc6dbd98f8..427556fe26 100644 --- a/plugins/shortcuts/src/setupTests.ts +++ b/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';