@atlassian/clientside-extensions 2.4.0-e0cce94-kuewz5ow

package/lib/ModalExtension.test.ts

@@ -0,0 +1,147 @@
+// eslint-disable-next-line node/no-extraneous-import
+import type { Dispatch, SetStateAction } from 'react';
+import type { ExtensionAPI } from '@atlassian/clientside-extensions-registry';
+import { onDebug } from '@atlassian/clientside-extensions-debug';
+import * as ModalExtension from './ModalExtension';
+
+jest.mock('@atlassian/clientside-extensions-debug');
+
+interface TestContext {
+    value?: number;
+}
+
+describe('ModalExtension', () => {
+    // @ts-expect-error - invalid values for type. Factory should overwrite it.
+    const testAttributesProvider: ModalExtension.ModalAttributesProvider = (api, context: TestContext) => {
+        api.onCleanup(jest.fn());
+        api.updateAttributes({});
+
+        return {
+            type: 'not-valid',
+            label: context.value === 42 ? 'The meaning of life' : 'A label',
+            onAction: jest.fn(),
+        };
+    };
+
+    const testAPI: ExtensionAPI<typeof testAttributesProvider> = {
+        onCleanup: jest.fn(),
+        updateAttributes: jest.fn(),
+    };
+
+    it('should generate the extension descriptor with the correct type', () => {
+        const extensionProvider = ModalExtension.factory(testAttributesProvider);
+        const extension = extensionProvider(testAPI, {});
+
+        // expect all attributes to be merged, and type to be overwritten with the correct value.
+        expect(extension).toEqual({
+            type: 'modal',
+            label: 'A label',
+            onAction: expect.any(Function),
+        });
+    });
+
+    it('should provide a extensionAPI object to the extension provider', () => {
+        expect(testAPI.onCleanup).toHaveBeenCalledTimes(0);
+        expect(testAPI.updateAttributes).toHaveBeenCalledTimes(0);
+
+        const extensionProvider = ModalExtension.factory(testAttributesProvider);
+        extensionProvider(testAPI, {});
+
+        expect(testAPI.onCleanup).toHaveBeenCalledTimes(1);
+        expect(testAPI.updateAttributes).toHaveBeenCalledTimes(1);
+    });
+
+    it('should share any provided context with the attributes provider', () => {
+        const extensionProvider = ModalExtension.factory(testAttributesProvider);
+        const extension = extensionProvider(testAPI, { value: 42 });
+
+        // expect label to change because of context
+        expect(extension).toEqual({
+            type: 'modal',
+            label: 'The meaning of life',
+            onAction: expect.any(Function),
+        });
+    });
+
+    it('should export all the supported appreanace for modals', () => {
+        expect(ModalExtension.Appearance).toBeTruthy();
+    });
+
+    it('should export all the supported sizes for modals', () => {
+        expect(ModalExtension.Width).toBeTruthy();
+    });
+
+    describe('API', () => {
+        let closeFn;
+        let api: ModalExtension.Api;
+        const el: HTMLElement = document.createElement('div');
+        const setStateFn: Dispatch<SetStateAction<ModalExtension.ModalAction[]>> = () => {};
+
+        beforeEach(() => {
+            closeFn = jest.fn();
+            api = new ModalExtension.Api(closeFn, setStateFn);
+        });
+
+        it('#onMount callback used in getRenderCallback', () => {
+            const cb = jest.fn();
+            api.onMount(cb);
+            api.getRenderCallback()(el);
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it('#onMount does nothing if not set', () => {
+            expect(() => {
+                api.getRenderCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onMount does nothing if callback is not function', () => {
+            // @ts-expect-error checking that non-TS consumers don't shoot themselves (or others) in the foot
+            api.onMount(null);
+            expect(() => {
+                api.getRenderCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onMount fails gracefully if callback throws error', () => {
+            api.onMount(() => {
+                throw Error('whoops');
+            });
+            expect(() => {
+                api.getRenderCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onUnmount callback used in getCleanupCallback', () => {
+            const cb = jest.fn();
+            api.onUnmount(cb);
+            api.getCleanupCallback()(el);
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it('#onUnmount does nothing if not set', () => {
+            expect(() => {
+                api.getCleanupCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onUnmount does nothing if callback is not function', () => {
+            // @ts-expect-error checking that non-TS consumers don't shoot themselves (or others) in the foot
+            api.onUnmount(null);
+            expect(() => {
+                api.getCleanupCallback()(el);
+            }).not.toThrow();
+            expect(onDebug).toHaveBeenCalledTimes(1);
+        });
+
+        it('#onUnmount fails gracefully if callback throws error', () => {
+            api.onUnmount(() => {
+                throw Error('whoops');
+            });
+            expect(() => {
+                api.getCleanupCallback()(el);
+            }).not.toThrow();
+            expect(onDebug).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/lib/ModalExtension.ts

@@ -0,0 +1,188 @@
+import type { ExtensionAttributes, ExtensionAttributesProvider } from '@atlassian/clientside-extensions-registry';
+import { onDebug } from '@atlassian/clientside-extensions-debug';
+import type {
+    Dispatch as ReactDispatch,
+    KeyboardEvent as ReactKeyboardEvent,
+    MouseEvent as ReactMouseEvent,
+    SetStateAction as ReactSetStateAction,
+    // eslint-disable-next-line node/no-extraneous-import
+} from 'react';
+
+import { ExtensionType } from './extension-type';
+import type { LifecycleCallback, MountableExtension } from './AbstractExtension';
+import { safeguard } from './AbstractExtension';
+
+// A type defined by the @atlaskit/modal-dialog
+type KeyboardOrMouseEvent = ReactMouseEvent<HTMLElement> | ReactKeyboardEvent<HTMLElement> | KeyboardEvent;
+
+interface ModalCloseCallback {
+    (e: KeyboardOrMouseEvent): boolean | void;
+}
+
+export type ModalAction = {
+    text: string;
+    onClick: () => void;
+    isDisabled?: boolean;
+    isLoading?: boolean;
+    testId?: string;
+};
+
+export type ModalRenderExtension = (api: Api) => void;
+
+export interface ModalAttributes extends ExtensionAttributes {
+    onAction: ModalRenderExtension;
+    label: string;
+    type?: ExtensionType.modal;
+}
+
+export type ModalAttributesProvider<ContextT> = ExtensionAttributesProvider<ModalAttributes, ContextT>;
+
+export const factory = <ContextT>(provider: ModalAttributesProvider<ContextT>): ModalAttributesProvider<ContextT> => {
+    return (...args) => {
+        const attributes = provider(...args);
+        return {
+            ...attributes,
+            type: ExtensionType.modal,
+        };
+    };
+};
+
+const noop = () => {};
+
+export enum Appearance {
+    'danger' = 'danger',
+    'warning' = 'warning',
+}
+
+export enum Width {
+    'small' = 'small',
+    'medium' = 'medium',
+    'large' = 'large',
+    'x-large' = 'x-large',
+}
+
+export class Api implements MountableExtension {
+    private title = '';
+
+    private width!: Width;
+
+    private appearance!: Appearance;
+
+    private renderCallback: LifecycleCallback = noop;
+
+    private cleanupCallback: LifecycleCallback = noop;
+
+    private readonly closeModalFn: () => void = noop;
+
+    private onCloseCallback: ModalCloseCallback = () => true;
+
+    constructor(closeModalFn: () => void, setActions: ReactDispatch<ReactSetStateAction<ModalAction[]>>) {
+        this.closeModalFn = safeguard('onClose', closeModalFn);
+
+        this.setActions = (actions) => {
+            setActions(Api.filterActionProps(actions));
+
+            return this;
+        };
+    }
+
+    public setTitle = (title: string) => {
+        this.title = title;
+
+        return this;
+    };
+
+    public setWidth = (width: Width) => {
+        // Runtime checking for 'non-ts' usage
+        if (!(width in Width)) {
+            onDebug(({ error }) => ({
+                level: error,
+                message: `Invalid value specified as "width" of modal. Please make sure to use one of the supported values.`,
+                meta: {
+                    value: width,
+                    supported: Object.keys(Width).concat(),
+                },
+            }));
+            return this;
+        }
+
+        this.width = width;
+        return this;
+    };
+
+    public setAppearance = (appearance: Appearance) => {
+        // Runtime checking for 'non-ts' usage
+        if (!(appearance in Appearance)) {
+            onDebug(({ error }) => ({
+                level: error,
+                message: `Invalid value specified as "appearance" of modal. Please make sure to use one of the supported values.`,
+                meta: {
+                    value: appearance,
+                    supported: Object.keys(Appearance).concat(),
+                },
+            }));
+            return this;
+        }
+
+        this.appearance = appearance;
+        return this;
+    };
+
+    public onMount = (callback: LifecycleCallback) => {
+        this.renderCallback = safeguard('onMount', callback);
+
+        return this;
+    };
+
+    public onUnmount = (callback: LifecycleCallback) => {
+        this.cleanupCallback = safeguard('onUnmount', callback);
+
+        return this;
+    };
+
+    public closeModal = () => {
+        this.closeModalFn();
+    };
+
+    public getTitle() {
+        return this.title;
+    }
+
+    public getWidth() {
+        return this.width;
+    }
+
+    public getAppearance() {
+        return this.appearance;
+    }
+
+    public getRenderCallback() {
+        return this.renderCallback;
+    }
+
+    public getCleanupCallback() {
+        return this.cleanupCallback;
+    }
+
+    public setActions: (actions: ModalAction[]) => void;
+
+    public onClose(callback: ModalCloseCallback) {
+        this.onCloseCallback = safeguard('onClose', callback);
+
+        return this;
+    }
+
+    public getOnCloseCallback() {
+        return this.onCloseCallback;
+    }
+
+    static filterActionProps(actions: unknown[]): ModalAction[] {
+        if (!Array.isArray(actions)) {
+            return [];
+        }
+
+        return actions.map(({ text, onClick, isDisabled, isLoading, testId }) => {
+            return { text, onClick, isDisabled, isLoading, testId };
+        });
+    }
+}

package/lib/PageExtension.test.ts

@@ -0,0 +1,38 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as PageExtension from './PageExtension';
+
+describe('PageExtension', () => {
+    it('should generate the extension shape', () => {
+        // given
+        const fakeRenderCallback = jest.fn();
+
+        // when
+        const extensionProvider = PageExtension.factory(fakeRenderCallback);
+        const extension = extensionProvider();
+
+        // then
+        expect(extension).toEqual({
+            type: 'page',
+            onAction: expect.any(Function),
+        });
+    });
+
+    it('should call the render callback', () => {
+        // given
+        const fakeRenderCallback = jest.fn();
+        const extensionProvider = PageExtension.factory(fakeRenderCallback);
+        const extension = extensionProvider();
+
+        const fakeNode = document.createElement('div');
+        const fakeDataProvider = { foo: 'bar' };
+
+        // when
+        extension.onAction(fakeNode, fakeDataProvider);
+
+        // then
+        expect(fakeRenderCallback).toHaveBeenCalledWith(fakeNode, fakeDataProvider);
+    });
+});

package/lib/PageExtension.ts

@@ -0,0 +1,21 @@
+import type { DataProviderPayload, ExtensionAttributes } from '@atlassian/clientside-extensions-registry';
+
+import { ExtensionType } from './extension-type';
+
+type RenderCallback<DataProviderT> = (node: HTMLElement, data: DataProviderPayload<DataProviderT>) => void;
+
+export interface PageAttributes<DataProviderT> extends ExtensionAttributes {
+    onAction: RenderCallback<DataProviderT>;
+    type: ExtensionType.page;
+}
+
+export type PageAttributesProvider<DataProviderT = unknown> = () => PageAttributes<DataProviderT>;
+
+export const factory = <DataProviderT>(renderCallback: RenderCallback<DataProviderT>): PageAttributesProvider<DataProviderT> => {
+    return () => ({
+        type: ExtensionType.page,
+        onAction: (node, data) => {
+            renderCallback(node, data);
+        },
+    });
+};

package/lib/PanelExtension.test.ts

@@ -0,0 +1,134 @@
+import type { ExtensionAPI } from '@atlassian/clientside-extensions-registry';
+import { onDebug } from '@atlassian/clientside-extensions-debug';
+import * as PanelExtension from './PanelExtension';
+
+jest.mock('@atlassian/clientside-extensions-debug');
+
+interface TestContext {
+    value?: number;
+}
+
+describe('PanelExtension', () => {
+    // @ts-expect-error - invalid values for type. Factory should overwrite it.
+    const testAttributesProvider: PanelExtension.PanelAttributesProvider = (api, context: TestContext) => {
+        api.onCleanup(jest.fn());
+        api.updateAttributes({});
+
+        return {
+            type: 'not-valid',
+            label: context.value === 42 ? 'The meaning of life' : 'A label',
+            onAction: jest.fn(),
+        };
+    };
+
+    const testAPI: ExtensionAPI<typeof testAttributesProvider> = {
+        onCleanup: jest.fn(),
+        updateAttributes: jest.fn(),
+    };
+
+    it('should generate the extension descriptor with the correct type', () => {
+        const extensionProvider = PanelExtension.factory(testAttributesProvider);
+        const extension = extensionProvider(testAPI, {});
+
+        // expect all attributes to be merged, and type to be overwritten with the correct value.
+        expect(extension).toEqual({
+            type: 'panel',
+            label: 'A label',
+            onAction: expect.any(Function),
+        });
+    });
+
+    it('should provide a extensionAPI object to the extension provider', () => {
+        expect(testAPI.onCleanup).toHaveBeenCalledTimes(0);
+        expect(testAPI.updateAttributes).toHaveBeenCalledTimes(0);
+
+        const extensionProvider = PanelExtension.factory(testAttributesProvider);
+        extensionProvider(testAPI, {});
+
+        expect(testAPI.onCleanup).toHaveBeenCalledTimes(1);
+        expect(testAPI.updateAttributes).toHaveBeenCalledTimes(1);
+    });
+
+    it('should share any provided context with the attributes provider', () => {
+        const extensionProvider = PanelExtension.factory(testAttributesProvider);
+        const extension = extensionProvider(testAPI, { value: 42 });
+
+        // expect label to change because of context
+        expect(extension).toEqual({
+            type: 'panel',
+            label: 'The meaning of life',
+            onAction: expect.any(Function),
+        });
+    });
+
+    describe('API', () => {
+        let api: PanelExtension.Api;
+        const el: HTMLElement = document.createElement('div');
+
+        beforeEach(() => {
+            api = new PanelExtension.Api();
+        });
+
+        it('#onMount callback used in getRenderCallback', () => {
+            const cb = jest.fn();
+            api.onMount(cb);
+            api.getRenderCallback()(el);
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it('#onMount does nothing if not set', () => {
+            expect(() => {
+                api.getRenderCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onMount does nothing if callback is not function', () => {
+            // @ts-expect-error checking that non-TS consumers don't shoot themselves (or others) in the foot
+            api.onMount(null);
+            expect(() => {
+                api.getRenderCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onMount fails gracefully if callback throws error', () => {
+            api.onMount(() => {
+                throw Error('whoops');
+            });
+            expect(() => {
+                api.getRenderCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onUnmount callback used in getCleanupCallback', () => {
+            const cb = jest.fn();
+            api.onUnmount(cb);
+            api.getCleanupCallback()(el);
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it('#onUnmount does nothing if not set', () => {
+            expect(() => {
+                api.getCleanupCallback()(el);
+            }).not.toThrow();
+        });
+
+        it('#onUnmount does nothing if callback is not function', () => {
+            // @ts-expect-error checking that non-TS consumers don't shoot themselves (or others) in the foot
+            api.onUnmount(null);
+            expect(() => {
+                api.getCleanupCallback()(el);
+            }).not.toThrow();
+            expect(onDebug).toHaveBeenCalledTimes(1);
+        });
+
+        it('#onUnmount fails gracefully if callback throws error', () => {
+            api.onUnmount(() => {
+                throw Error('whoops');
+            });
+            expect(() => {
+                api.getCleanupCallback()(el);
+            }).not.toThrow();
+            expect(onDebug).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/lib/PanelExtension.ts

@@ -0,0 +1,51 @@
+import type { Context, ExtensionAttributes, ExtensionAttributesProvider } from '@atlassian/clientside-extensions-registry';
+
+import { ExtensionType } from './extension-type';
+import type { LifecycleCallback, MountableExtension } from './AbstractExtension';
+import { safeguard } from './AbstractExtension';
+
+export type PanelRenderExtension = (api: Api, context?: Context<{}>, data?: unknown) => void;
+
+export interface PanelAttributes extends ExtensionAttributes {
+    onAction: PanelRenderExtension;
+    type?: ExtensionType.panel;
+}
+
+export type PanelAttributesProvider<ContextT> = ExtensionAttributesProvider<PanelAttributes, ContextT>;
+
+export const factory = <ContextT>(provider: PanelAttributesProvider<ContextT>): PanelAttributesProvider<ContextT> => {
+    return (...args) => {
+        return {
+            ...provider(...args),
+            type: ExtensionType.panel,
+        };
+    };
+};
+
+const noop = () => {};
+
+export class Api implements MountableExtension {
+    private renderCallback: LifecycleCallback = noop;
+
+    private cleanupCallback: LifecycleCallback = noop;
+
+    public onMount(callback: LifecycleCallback) {
+        this.renderCallback = safeguard('onMount', callback);
+
+        return this;
+    }
+
+    public onUnmount(callback: LifecycleCallback) {
+        this.cleanupCallback = safeguard('onUnmount', callback);
+
+        return this;
+    }
+
+    public getRenderCallback() {
+        return this.renderCallback;
+    }
+
+    public getCleanupCallback() {
+        return this.cleanupCallback;
+    }
+}

package/lib/SectionExtension.test.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI } from '@atlassian/clientside-extensions-registry';
+import * as SectionExtension from './SectionExtension';
+import type { SectionAttributesProvider } from './SectionExtension';
+
+interface TestContext {
+    value?: number;
+}
+
+describe('SectionExtension', () => {
+    // @ts-expect-error we set the invalid type
+    const testAttributesProvider: SectionAttributesProvider = (api, context: TestContext) => {
+        api.onCleanup(jest.fn());
+        api.updateAttributes({});
+
+        return {
+            type: 'not-valid',
+            label: context.value === 42 ? 'The meaning of life' : 'A label',
+        };
+    };
+    const testAPI: ExtensionAPI<typeof testAttributesProvider> = {
+        onCleanup: jest.fn(),
+        updateAttributes: jest.fn(),
+    };
+
+    it('should generate the extension descriptor with the correct type', () => {
+        const extensionProvider = SectionExtension.factory(testAttributesProvider);
+        const extension = extensionProvider(testAPI, {});
+
+        // expect all attributes to be merged, and type to be overwritten with the correct value.
+        expect(extension).toEqual({
+            type: 'section',
+            label: 'A label',
+        });
+    });
+
+    it('should provide a extensionAPI object to the extension provider', () => {
+        expect(testAPI.onCleanup).toHaveBeenCalledTimes(0);
+        expect(testAPI.updateAttributes).toHaveBeenCalledTimes(0);
+
+        const extensionProvider = SectionExtension.factory(testAttributesProvider);
+        extensionProvider(testAPI, {});
+
+        expect(testAPI.onCleanup).toHaveBeenCalledTimes(1);
+        expect(testAPI.updateAttributes).toHaveBeenCalledTimes(1);
+    });
+
+    it('should share any provided context with the attributes provider', () => {
+        const extensionProvider = SectionExtension.factory(testAttributesProvider);
+        const extension = extensionProvider(testAPI, { value: 42 });
+
+        // expect label to change because of context
+        expect(extension).toEqual({
+            type: 'section',
+            label: 'The meaning of life',
+        });
+    });
+});

package/lib/SectionExtension.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAttributes, ExtensionAttributesProvider } from '@atlassian/clientside-extensions-registry';
+
+import { ExtensionType } from './extension-type';
+
+export interface SectionAttributes extends ExtensionAttributes {
+    type?: ExtensionType.section;
+}
+
+export type SectionAttributesProvider<ContextT> = ExtensionAttributesProvider<SectionAttributes, ContextT>;
+
+export const factory = <ContextT>(provider: SectionAttributesProvider<ContextT>): SectionAttributesProvider<ContextT> => {
+    return (...args) => {
+        return {
+            ...provider(...args),
+            type: ExtensionType.section,
+        };
+    };
+};

package/lib/extension-type.ts

@@ -0,0 +1,10 @@
+// eslint-disable-next-line import/prefer-default-export
+export enum ExtensionType {
+    'asyncPanel' = 'async-panel',
+    button = 'button',
+    link = 'link',
+    modal = 'modal',
+    panel = 'panel',
+    page = 'page',
+    section = 'section',
+}

package/lib/index.ts

@@ -0,0 +1,21 @@
+import * as AsyncPanelExtension from './AsyncPanelExtension';
+import * as ButtonExtension from './ButtonExtension';
+import * as LinkExtension from './LinkExtension';
+import * as ModalExtension from './ModalExtension';
+import * as PanelExtension from './PanelExtension';
+import * as SectionExtension from './SectionExtension';
+import * as PageExtension from './PageExtension';
+import { ExtensionType } from './extension-type';
+
+export type { MountableExtension, LifecycleCallback } from './AbstractExtension';
+
+export {
+    AsyncPanelExtension,
+    ButtonExtension,
+    LinkExtension,
+    ModalExtension,
+    PanelExtension,
+    SectionExtension,
+    PageExtension,
+    ExtensionType,
+};