@forge/react 10.2.0-next.0 → 10.2.1-next.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @forge/react
 
+## 10.2.1-next.0
+
+### Patch Changes
+
+- 028fcfc: Include JSComments to be included in the build output
+
+## 10.2.0
+
+### Minor Changes
+
+- e14a6c7: Add Frame component support in UI Kit [EAP].
+
+  For more information, see the [Frame component documentation](https://developer.atlassian.com/platform/forge/ui-kit/components/frame).
+
 ## 10.2.0-next.0
 
 ### Minor Changes

package/out/__test__/hostConfig.test.js

@@ -48,7 +48,7 @@ describe('hostConfig used functions', () => {
             reconciler_1.hostConfig.appendChild(parent, child);
             expect(parent).toHaveProperty('children', [child]);
             reconciler_1.hostConfig.appendChild(parent, child);
-            expect(parent).toHaveProperty('children', [child]);
+            expect(parent).toHaveProperty('children', [child]); // Still just one child!
         }
     });
     it('appendChildToContainer', () => {
@@ -142,6 +142,11 @@ describe('hostConfig used functions', () => {
         }
     });
 });
+// The reason for including the following tests is to ensure that any changes to the
+// HostConfig are verified both in the source and in the tests. The need to check that
+// some of the functions are even defined indicates that we don't need to declare
+// all the functions in the reconciler, but keeping them with the tets ensures we do the
+// appropriate due diligence on any changes. It also ensures we have good code coverage!
 describe('hostConfig unused functions', () => {
     it('should return empty object from getRootHostContext', () => {
         expect(reconciler_1.hostConfig.getRootHostContext(emptyForgeDoc)).toEqual({});

package/out/__test__/reconciler.test.js

@@ -33,13 +33,14 @@ describe('Reconcilation', () => {
     });
     it('forgeDoc is created on initial render', () => {
         const forgeDoc = (0, testUtils_1.getLastBridgeCallForgeDoc)(bridgeCalls);
-        expect(forgeDoc).toHaveProperty(`children[${TEXT}].type`, 'Text');
-        expect(forgeDoc).toHaveProperty(`children[${BUTTON}].type`, 'Button');
+        expect(forgeDoc).toHaveProperty(`children[${TEXT}].type`, 'Text'); // First child is text
+        expect(forgeDoc).toHaveProperty(`children[${BUTTON}].type`, 'Button'); // Second child is button
         expect(forgeDoc).toHaveProperty(`children[${STATIC_TEXT}].type`, 'Lozenge');
         expect(forgeDoc).toMatchSnapshot();
     });
     it('forgeDoc is updated on state update', () => {
         let forgeDoc = (0, testUtils_1.getLastBridgeCallForgeDoc)(bridgeCalls);
+        // Get the click handler for the 1st button
         const onClick = (0, get_1.default)(forgeDoc, `children[${BUTTON}].props.onClick`);
         expect(onClick).not.toBeUndefined();
         onClick();

package/out/__test__/reconcilerTestRenderer.js

@@ -4,6 +4,8 @@ exports.addConfig = exports.create = void 0;
 const tslib_1 = require("tslib");
 const React = tslib_1.__importStar(require("react"));
 const reconciler_1 = require("../reconciler");
+// NOTE: This only works with React 18
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const _act = React.unstable_act;
 const act = _act;
 const create = async (element) => {

package/out/__test__/testUtils.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findElementInForgeDoc = exports.getLastBridgeCallForgeDoc = exports.getLastBridgeCall = exports.setupBridge = void 0;
+// In an actual UI Kit 2 application the bridge is added to the global namespace by scripts served
+// from the Forge CDN. In order to be able to test our reconciler we need to see what data is being
+// passed over the bridge. This function simulates the function and allows tests to access all the
+// calls that are made.
 const setupBridge = () => {
     const bridgeCalls = [];
+    // @ts-ignore
     global['self'] = {
         __bridge: {
+            // @ts-ignore to get past type error from new tsconfig lib
             callBridge: (cmd, data) => {
                 bridgeCalls.push({ cmd, data });
             }

package/out/components/index.d.ts

@@ -9,7 +9,15 @@ export declare const UserGroup: (props: UserGroupProps) => ForgeElement;
 export declare const Em: (props: MarkupProps) => ForgeElement;
 export declare const Strike: (props: MarkupProps) => ForgeElement;
 export declare const Strong: (props: MarkupProps) => ForgeElement;
+/**
+ * `Frame` component is in EAP (Early Access Program).
+ *
+ * For more information, see the {@link https://developer.atlassian.com/platform/forge/ui-kit/components/frame|Frame component} documentation.
+ */
 export declare const Frame: (props: FrameProps) => ForgeElement;
+/**
+ * Export Code generated UI Kit 2 Components
+ */
 export * from './uikit2-components';
 declare type CheckboxGroupProps = {
     name: string;

package/out/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,gBAAgB,IAAI,UAAU,EAC9B,eAAe,IAAI,SAAS,EAC5B,eAAe,IAAI,SAAS,EAC5B,qBAAqB,IAAI,eAAe,EACxC,cAAc,EACd,SAAS,EACT,UAAU,EACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,eAAO,MAAM,KAAK,UAAiC,UAAU,KAAK,YAAY,CAAC;AAC/E,eAAO,MAAM,IAAI,UAAgC,SAAS,KAAK,YAAY,CAAC;AAC5E,eAAO,MAAM,IAAI,UAAgC,SAAS,KAAK,YAAY,CAAC;AAC5E,eAAO,MAAM,UAAU,UAAsC,eAAe,KAAK,YAAY,CAAC;AAC9F,eAAO,MAAM,IAAI,UAAgC,SAAS,KAAK,YAAY,CAAC;AAC5E,eAAO,MAAM,SAAS,UAAqC,cAAc,KAAK,YAAY,CAAC;AAE3F,eAAO,MAAM,EAAE,UAA8B,WAAW,KAAK,YAAY,CAAC;AAC1E,eAAO,MAAM,MAAM,UAAkC,WAAW,KAAK,YAAY,CAAC;AAClF,eAAO,MAAM,MAAM,UAAkC,WAAW,KAAK,YAAY,CAAC;AAOlF,eAAO,MAAM,KAAK,UAAiC,UAAU,KAAK,YAAY,CAAC;AAK/E,cAAc,qBAAqB,CAAC;AAGpC,aAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnD,CAAC;AACF,eAAO,MAAM,aAAa,UAAyC,kBAAkB,KAAK,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,gBAAgB,IAAI,UAAU,EAC9B,eAAe,IAAI,SAAS,EAC5B,eAAe,IAAI,SAAS,EAC5B,qBAAqB,IAAI,eAAe,EACxC,cAAc,EACd,SAAS,EACT,UAAU,EACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,eAAO,MAAM,KAAK,UAAiC,UAAU,KAAK,YAAY,CAAC;AAC/E,eAAO,MAAM,IAAI,UAAgC,SAAS,KAAK,YAAY,CAAC;AAC5E,eAAO,MAAM,IAAI,UAAgC,SAAS,KAAK,YAAY,CAAC;AAC5E,eAAO,MAAM,UAAU,UAAsC,eAAe,KAAK,YAAY,CAAC;AAC9F,eAAO,MAAM,IAAI,UAAgC,SAAS,KAAK,YAAY,CAAC;AAC5E,eAAO,MAAM,SAAS,UAAqC,cAAc,KAAK,YAAY,CAAC;AAE3F,eAAO,MAAM,EAAE,UAA8B,WAAW,KAAK,YAAY,CAAC;AAC1E,eAAO,MAAM,MAAM,UAAkC,WAAW,KAAK,YAAY,CAAC;AAClF,eAAO,MAAM,MAAM,UAAkC,WAAW,KAAK,YAAY,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,KAAK,UAAiC,UAAU,KAAK,YAAY,CAAC;AAE/E;;GAEG;AACH,cAAc,qBAAqB,CAAC;AAGpC,aAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnD,CAAC;AACF,eAAO,MAAM,aAAa,UAAyC,kBAAkB,KAAK,YAAY,CAAC"}

package/out/components/index.js

@@ -11,6 +11,14 @@ exports.UserGroup = 'UserGroup';
 exports.Em = 'Em';
 exports.Strike = 'Strike';
 exports.Strong = 'Strong';
+/**
+ * `Frame` component is in EAP (Early Access Program).
+ *
+ * For more information, see the {@link https://developer.atlassian.com/platform/forge/ui-kit/components/frame|Frame component} documentation.
+ */
 exports.Frame = 'Frame';
+/**
+ * Export Code generated UI Kit 2 Components
+ */
 tslib_1.__exportStar(require("./uikit2-components"), exports);
 exports.CheckboxGroup = 'CheckboxGroup';

package/out/components/uikit2-components.js

@@ -50,4 +50,5 @@ exports.Textfield = 'Textfield';
 exports.Toggle = 'Toggle';
 exports.Tooltip = 'Tooltip';
 exports.ValidMessage = 'ValidMessage';
+// Additional components without props
 exports.RequiredAsterisk = 'RequiredAsterisk';

package/out/hooks/__test__/confluenceEntity.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+// defining mock functions above import so they are initialised before jest.mock runs
 const mockRequestConf = jest.fn();
 const mockGetContext = jest.fn(async () => mockPropertyHook_1.mockConfContext);
 const confluenceEntity_1 = require("../confluenceEntity");
@@ -54,7 +55,7 @@ describe('confluenceEntity', () => {
         it('if the property exists, it should return its value', async () => {
             const output = await contentEntity.get();
             expect(output).toEqual(mockPropertyHook_1.EXISTING_PROP_VALUE);
-            expect(mockRequestConf).toHaveBeenCalledTimes(1);
+            expect(mockRequestConf).toHaveBeenCalledTimes(1); // stop making further requests
         });
         it('should throw an error if the GET request fails', async () => {
             mockRequestConf.mockResolvedValueOnce(mockPropertyHook_1.mockFailedRes);
@@ -93,6 +94,7 @@ describe('confluenceEntity', () => {
             const contentGetUrl = contentEndpoints.fetch('forge-MOCK_LOCAL_ID-MOCK_PROP_KEY');
             const contentGetBody = expect.objectContaining({ method: 'GET' });
             const contentPutUrl = contentEndpoints.update('MOCK_PROP_ID');
+            // both value & version props need to be present in body string
             const valueUpdateStr = `"value":${mockPropertyHook_1.UPDATED_PROP_VALUE}`;
             const versionUpdateStr = `"version":{"number":${mockPropertyHook_1.UPDATED_PROP_VALUE}`;
             const contentPutBody = (updateStr) => expect.objectContaining({

package/out/hooks/__test__/jiraEntity.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+// defining mock functions above import so they are initialised before jest.mock runs
 const mockRequestJira = jest.fn();
 const mockGetContext = jest.fn(async () => mockPropertyHook_1.mockJiraContext);
 const jiraEntity_1 = require("../jiraEntity");
@@ -48,7 +49,7 @@ describe('jiraIssuePropsManager', () => {
         it('if the property exists, it should return its value', async () => {
             const output = await issueProps.get();
             expect(output).toEqual(mockPropertyHook_1.EXISTING_PROP_VALUE);
-            expect(mockRequestJira).toHaveBeenCalledTimes(1);
+            expect(mockRequestJira).toHaveBeenCalledTimes(1); // stop making further requests
         });
         it('should throw an error if the GET request fails', async () => {
             mockRequestJira.mockResolvedValueOnce(mockPropertyHook_1.mockFailedRes);

package/out/hooks/__test__/mockPropertyHook.d.ts

@@ -2,6 +2,9 @@ import type { EntityContext } from '../types';
 export declare const DEFAULT_PROP_VALUE: number, EXISTING_PROP_VALUE: number, UPDATED_PROP_VALUE: number;
 export declare const mockConfContext: EntityContext;
 export declare const mockJiraContext: EntityContext;
+/**
+ * Mock functions for API calls
+ */
 export declare const mockFailedRes: {
     ok: boolean;
     status: number;

package/out/hooks/__test__/mockPropertyHook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mockPropertyHook.d.ts","sourceRoot":"","sources":["../../../src/hooks/__test__/mockPropertyHook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,eAAO,MAAO,kBAAkB,UAAE,mBAAmB,UAAE,kBAAkB,QAAa,CAAC;AAEvF,eAAO,MAAM,eAAe,EAAE,aAU7B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,aAO7B,CAAC;AAKF,eAAO,MAAM,aAAa;;;CAGzB,CAAC;AACF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;CAMlC,CAAC;AACF,eAAO,MAAM,yBAAyB;;;;;;CAMrC,CAAC;AACF,eAAO,MAAM,iBAAiB;;;;;;;CAI7B,CAAC;AACF,eAAO,MAAM,sBAAsB;;;;;;;CAIlC,CAAC;AACF,eAAO,MAAM,yBAAyB;;;;;;;CAIrC,CAAC;AACF,eAAO,MAAM,iBAAiB;;;CAG7B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;CAG9B,CAAC;AACF,eAAO,MAAM,sBAAsB;;;;;;;CAIlC,CAAC;AACF,eAAO,MAAM,yBAAyB;;;CAGrC,CAAC"}
+{"version":3,"file":"mockPropertyHook.d.ts","sourceRoot":"","sources":["../../../src/hooks/__test__/mockPropertyHook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,eAAO,MAAO,kBAAkB,UAAE,mBAAmB,UAAE,kBAAkB,QAAa,CAAC;AAEvF,eAAO,MAAM,eAAe,EAAE,aAU7B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,aAO7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;;CAGzB,CAAC;AACF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;CAMlC,CAAC;AACF,eAAO,MAAM,yBAAyB;;;;;;CAMrC,CAAC;AACF,eAAO,MAAM,iBAAiB;;;;;;;CAI7B,CAAC;AACF,eAAO,MAAM,sBAAsB;;;;;;;CAIlC,CAAC;AACF,eAAO,MAAM,yBAAyB;;;;;;;CAIrC,CAAC;AACF,eAAO,MAAM,iBAAiB;;;CAG7B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;CAG9B,CAAC;AACF,eAAO,MAAM,sBAAsB;;;;;;;CAIlC,CAAC;AACF,eAAO,MAAM,yBAAyB;;;CAGrC,CAAC"}

package/out/hooks/__test__/mockPropertyHook.js

@@ -2,6 +2,7 @@
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mockJiraGetNonExistentRes = exports.mockJiraGetExistingRes = exports.mockJiraSuccessRes = exports.mockConfDeleteRes = exports.mockConfUpdateFunctionRes = exports.mockConfUpdateValueRes = exports.mockConfCreateRes = exports.mockConfGetNonExistentRes = exports.mockConfGetExistingRes = exports.mockFailedRes = exports.mockJiraContext = exports.mockConfContext = exports.UPDATED_PROP_VALUE = exports.EXISTING_PROP_VALUE = exports.DEFAULT_PROP_VALUE = void 0;
+// mock property values
 _a = [1, 2, 3], exports.DEFAULT_PROP_VALUE = _a[0], exports.EXISTING_PROP_VALUE = _a[1], exports.UPDATED_PROP_VALUE = _a[2];
 exports.mockConfContext = {
     localId: 'MOCK_LOCAL_ID',
@@ -22,6 +23,9 @@ exports.mockJiraContext = {
         }
     }
 };
+/**
+ * Mock functions for API calls
+ */
 exports.mockFailedRes = {
     ok: false,
     status: 400
@@ -59,6 +63,7 @@ exports.mockConfDeleteRes = {
     ok: true,
     status: 204
 };
+// jira issue responses
 exports.mockJiraSuccessRes = {
     ok: true,
     status: 201

package/out/hooks/__test__/useConfig.test.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const jsx_runtime_1 = require("react/jsx-runtime");
+// defining mock function above import so it is initialised before jest.mock runs
 const mockGetContext = jest.fn(async () => null);
 const react_1 = tslib_1.__importStar(require("react"));
 const reconcilerTestRenderer_1 = tslib_1.__importDefault(require("../../__test__/reconcilerTestRenderer"));
@@ -24,6 +25,7 @@ const MOCK_CONTEXT_NO_CONFIG = {
     extension: {}
 };
 const configListener = jest.fn();
+// react app fragment to be load useProductContext hook
 const renderTest = async () => {
     const Test = () => {
         const config = (0, useConfig_1.useConfig)();
@@ -43,7 +45,8 @@ describe('useConfig', () => {
     it('when there is no config, outputs undefined', async () => {
         mockGetContext.mockResolvedValue(MOCK_CONTEXT_NO_CONFIG);
         await renderTest();
-        expect(configListener.mock.calls[0][0]).toEqual(undefined);
+        expect(configListener.mock.calls[0][0]).toEqual(undefined); // initial rendered value
+        // no change to undef value after productContext call, do not re-render
         expect(configListener).not.toHaveBeenNthCalledWith(2, expect.anything);
     });
 });

package/out/hooks/__test__/useEntityProperty.test.js

@@ -42,7 +42,7 @@ const renderTest = async (action = renderActions.noAction, retryCount) => {
         (0, react_1.useEffect)(() => {
             if (action === renderActions.toUpdate) {
                 setProp(mockPropertyHook_1.UPDATED_PROP_VALUE, retryCount).catch((err) => {
-                    console.error(err);
+                    console.error(err); // eslint-disable-line no-console
                 });
             }
             if (action === renderActions.toDelete) {
@@ -84,7 +84,7 @@ describe('useEntityProperty', () => {
         it('makes 2 retries (by default) when initial attempt fails', async () => {
             mockRequest.mockResolvedValue(() => mockPropertyHook_1.mockFailedRes);
             await renderTest(renderActions.toUpdate);
-            expect(mockRequest).toHaveBeenNthCalledWith(2, 'update');
+            expect(mockRequest).toHaveBeenNthCalledWith(2, 'update'); // initial attempt
             expect(mockRequest).toHaveBeenNthCalledWith(3, 'update');
             expect(mockRequest).toHaveBeenNthCalledWith(4, 'update');
             expect(mockRequest).not.toHaveBeenNthCalledWith(5, 'update');
@@ -92,7 +92,7 @@ describe('useEntityProperty', () => {
         it('stops retrying when a previous retry succeeds', async () => {
             mockRequest.mockResolvedValueOnce(() => mockPropertyHook_1.mockFailedRes).mockResolvedValueOnce(() => mockPropertyHook_1.mockConfUpdateValueRes);
             await renderTest(renderActions.toUpdate);
-            expect(mockRequest).toHaveBeenNthCalledWith(2, 'update');
+            expect(mockRequest).toHaveBeenNthCalledWith(2, 'update'); // initial attempt
             expect(mockRequest).toHaveBeenNthCalledWith(3, 'update');
             expect(mockRequest).not.toHaveBeenNthCalledWith(4, 'update');
         });

package/out/hooks/__test__/useProductContext.test.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const jsx_runtime_1 = require("react/jsx-runtime");
+// defining mock function above import so it is initialised before jest.mock runs
 const mockGetContext = jest.fn(async () => null);
 const useProductContext_1 = require("../useProductContext");
 const react_1 = tslib_1.__importStar(require("react"));
@@ -24,6 +25,7 @@ const MOCK_CONTEXT = {
     timezone: 'DUMMY-timezone'
 };
 const prodContListener = jest.fn();
+// react app fragment to be load useProductContext hook
 const renderTest = async () => {
     const Test = () => {
         const prodCont = (0, useProductContext_1.useProductContext)();
@@ -52,7 +54,7 @@ describe('useProductContext', () => {
         });
         await renderTest();
         expect(prodContListener).not.toHaveBeenNthCalledWith(2, expect.anything());
-        await new Promise((res) => setTimeout(res, LOAD_TIME * 2));
+        await new Promise((res) => setTimeout(res, LOAD_TIME * 2)); // wait for data to load
         expect(prodContListener.mock.calls[1][0]).toEqual(MOCK_CONTEXT);
     }, LOAD_TIME * 3);
 });

package/out/hooks/confluenceEntity.d.ts

@@ -1,4 +1,8 @@
 import type { ConfEndpointInitializer, ManagePropsData, ConfluenceEntityType, EntityManager } from './types';
+/**
+ * given an entityType and a product context, returns functions that uses property data to
+ * output URLs to use for property management via Confluence v2 REST API
+ */
 export declare const confAPIEndpoints: ({ entityType, context }: ConfEndpointInitializer) => {
     create: () => string;
     fetch: (propertyKey: string) => string;

package/out/hooks/confluenceEntity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"confluenceEntity.d.ts","sourceRoot":"","sources":["../../src/hooks/confluenceEntity.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,uBAAuB,EAEvB,eAAe,EACf,oBAAoB,EACpB,aAAa,EAEd,MAAM,SAAS,CAAC;AAMjB,eAAO,MAAM,gBAAgB,4BAA6B,uBAAuB;;yBAqBxD,MAAM;yBACN,MAAM;yBACN,MAAM;CAE9B,CAAC;AAEF,eAAO,MAAM,gBAAgB;gBAIiB,oBAAoB;8BAqGjE,CAAC"}
+{"version":3,"file":"confluenceEntity.d.ts","sourceRoot":"","sources":["../../src/hooks/confluenceEntity.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,uBAAuB,EAEvB,eAAe,EACf,oBAAoB,EACpB,aAAa,EAEd,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,eAAO,MAAM,gBAAgB,4BAA6B,uBAAuB;;yBAqBxD,MAAM;yBACN,MAAM;yBACN,MAAM;CAE9B,CAAC;AAEF,eAAO,MAAM,gBAAgB;gBAIiB,oBAAoB;8BAqGjE,CAAC"}

package/out/hooks/confluenceEntity.js

@@ -5,6 +5,10 @@ const bridge_1 = require("@forge/bridge");
 const apiRequestUtils_1 = require("./utils/apiRequestUtils");
 const valueUtils_1 = require("./utils/valueUtils");
 const types_1 = require("./types");
+/**
+ * given an entityType and a product context, returns functions that uses property data to
+ * output URLs to use for property management via Confluence v2 REST API
+ */
 const confAPIEndpoints = ({ entityType, context }) => {
     let entityId, urlEntity;
     switch (entityType) {
@@ -40,6 +44,7 @@ const confluenceEntity = ({ entityType, origPropertyKey, initValue }) => {
             origPropertyKey
         });
     };
+    // fetches existing prop value from server. to be reused for GET, UPDATE, DELETE operations
     const fetchOriginal = async ({ endpointFactory, propertyKey }) => {
         const url = endpointFactory.fetch(propertyKey);
         const response = await (0, apiRequestUtils_1.makeRequest)({ url, apiMethod, method: 'GET' });
@@ -47,7 +52,9 @@ const confluenceEntity = ({ entityType, origPropertyKey, initValue }) => {
         const existingData = await (0, apiRequestUtils_1.getJSONData)(response);
         return existingData.results[0];
     };
+    // named `deleteProp` since `delete` is reserved word
     const deleteProp = async ({ endpointFactory, propertyKey }) => {
+        // fetch original prop first to get its id
         const originalProp = await fetchOriginal({ endpointFactory, propertyKey });
         if (!originalProp) {
             throw new types_1.EntityPropertyRequestFailedError({
@@ -67,6 +74,7 @@ const confluenceEntity = ({ entityType, origPropertyKey, initValue }) => {
         if (existingProp) {
             return existingProp.value;
         }
+        // if property doesn't exist, create it
         const resolvedInitVal = await (0, valueUtils_1.resolveValue)(initValue);
         const url = endpointFactory.create();
         const body = JSON.stringify({ key: propertyKey, value: resolvedInitVal });
@@ -75,6 +83,7 @@ const confluenceEntity = ({ entityType, origPropertyKey, initValue }) => {
         return (await (0, apiRequestUtils_1.getJSONData)(response)).value;
     };
     const update = async ({ endpointFactory, propertyKey }, valueUpdate) => {
+        // fetch original prop first to update based on its value + version + id
         const originalProp = await fetchOriginal({ endpointFactory, propertyKey });
         if (!originalProp) {
             throw new types_1.EntityPropertyRequestFailedError({

package/out/hooks/jiraEntity.d.ts

@@ -1,4 +1,8 @@
 import type { EntityContext, ManagePropsData } from './types';
+/**
+ * given a context, returns functions that uses property data to
+ * output URLs to use for issue property management via Jira v2 REST API
+ */
 export declare const issueAPIEndpoints: (context: EntityContext) => {
     create: () => string;
     fetch: (propertyKey: string) => string;

package/out/hooks/jiraEntity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jiraEntity.d.ts","sourceRoot":"","sources":["../../src/hooks/jiraEntity.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAe,eAAe,EAAyB,MAAM,SAAS,CAAC;AAMlG,eAAO,MAAM,iBAAiB,YAAa,aAAa;;yBAM/B,MAAM;0BACL,MAAM;0BACN,MAAM;CAE/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;CA6GjC,CAAC"}
+{"version":3,"file":"jiraEntity.d.ts","sourceRoot":"","sources":["../../src/hooks/jiraEntity.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAe,eAAe,EAAyB,MAAM,SAAS,CAAC;AAElG;;;GAGG;AACH,eAAO,MAAM,iBAAiB,YAAa,aAAa;;yBAM/B,MAAM;0BACL,MAAM;0BACN,MAAM;CAE/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;CA6GjC,CAAC"}

package/out/hooks/jiraEntity.js

@@ -5,6 +5,10 @@ const bridge_1 = require("@forge/bridge");
 const apiRequestUtils_1 = require("./utils/apiRequestUtils");
 const valueUtils_1 = require("./utils/valueUtils");
 const types_1 = require("./types");
+/**
+ * given a context, returns functions that uses property data to
+ * output URLs to use for issue property management via Jira v2 REST API
+ */
 const issueAPIEndpoints = (context) => {
     const issueId = context.extension.issue?.id;
     if (!issueId)
@@ -28,6 +32,7 @@ const jiraIssuePropsManager = ({ origPropertyKey, initValue }) => {
             origPropertyKey
         });
     };
+    // fetches existing prop value from server. to be reused for GET, UPDATE, DELETE operations
     const fetchOriginal = async ({ endpointFactory, propertyKey }) => {
         const url = endpointFactory.fetch(propertyKey);
         const response = await (0, apiRequestUtils_1.makeRequest)({ url, apiMethod, method: 'GET' });
@@ -45,6 +50,7 @@ const jiraIssuePropsManager = ({ origPropertyKey, initValue }) => {
         const existingData = await (0, apiRequestUtils_1.getJSONData)(response);
         return existingData;
     };
+    // named `deleteProp` since `delete` is reserved word
     const deleteProp = async ({ endpointFactory, propertyKey }) => {
         const url = endpointFactory.delete(propertyKey);
         const response = await (0, apiRequestUtils_1.makeRequest)({ url, apiMethod, method: 'DELETE' });
@@ -55,6 +61,7 @@ const jiraIssuePropsManager = ({ origPropertyKey, initValue }) => {
         if (existingProp) {
             return existingProp.value;
         }
+        // if property doesn't exist, create it
         const resolvedInitVal = await (0, valueUtils_1.resolveValue)(initValue);
         const url = endpointFactory.create();
         const entityId = context.extension.issue?.id;
@@ -75,9 +82,11 @@ const jiraIssuePropsManager = ({ origPropertyKey, initValue }) => {
     };
     const update = async ({ endpointFactory, propertyKey, context }, valueUpdate) => {
         const newValueOrRunUpdaterOnOriginal = async (valueUpdate) => {
+            // concrete value update, does not require fetching original value
             if (!(valueUpdate instanceof Function)) {
                 return valueUpdate;
             }
+            // value update via function, fetch original prop first to update based on its value
             const originalProp = await fetchOriginal({ endpointFactory, propertyKey, context });
             if (!originalProp) {
                 throw new types_1.EntityPropertyRequestFailedError({

package/out/hooks/useContentProperty.d.ts

@@ -1,2 +1,11 @@
+/**
+ * This function manages the content properties of a Confluence page where the app is installed.
+ * @param propertyKey Name (key) of the property
+ * @param initValue Default value if it did not exist previously
+ * @returns An array with 3 items:
+ *  1. Current value of the property.
+ *  2. A function to update the property value (with another value or an updater function). If an initial update fails, it automatically tries to update for another <retryCount> times (default 2).
+ *  3. A function to delete the property.
+ */
 export declare const useContentProperty: <PropValue>(propertyKey: string, initValue: PropValue) => readonly [PropValue | undefined, (valueUpdate: import("./types/entityProps").ValueUpdate<PropValue>, retryCount?: number) => Promise<void>, () => Promise<void>];
 //# sourceMappingURL=useContentProperty.d.ts.map

package/out/hooks/useContentProperty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useContentProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useContentProperty.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,kBAAkB,2BAA4B,MAAM,2LAWhE,CAAC"}
+{"version":3,"file":"useContentProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useContentProperty.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,2BAA4B,MAAM,2LAWhE,CAAC"}

package/out/hooks/useContentProperty.js

@@ -4,6 +4,15 @@ exports.useContentProperty = void 0;
 const react_1 = require("react");
 const confluenceEntity_1 = require("./confluenceEntity");
 const useEntityProperty_1 = require("./useEntityProperty");
+/**
+ * This function manages the content properties of a Confluence page where the app is installed.
+ * @param propertyKey Name (key) of the property
+ * @param initValue Default value if it did not exist previously
+ * @returns An array with 3 items:
+ *  1. Current value of the property.
+ *  2. A function to update the property value (with another value or an updater function). If an initial update fails, it automatically tries to update for another <retryCount> times (default 2).
+ *  3. A function to delete the property.
+ */
 const useContentProperty = (propertyKey, initValue) => {
     const entityManager = (0, react_1.useMemo)(() => (0, confluenceEntity_1.confluenceEntity)({
         entityType: 'Content',

package/out/hooks/useEntityProperty.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useEntityProperty = void 0;
+/**
+ * React-based property management hook for Confluence API and entities
+ */
 const react_1 = require("react");
+// outputs a stateful variable and a function to update it
 const useEntityProperty = ({ entityManager, defaultRetryCount = 2 }) => {
     const [propValue, setPropValue] = (0, react_1.useState)();
     (0, react_1.useEffect)(() => {
@@ -10,6 +14,7 @@ const useEntityProperty = ({ entityManager, defaultRetryCount = 2 }) => {
             setPropValue(currentVal);
         };
         getProp().catch(() => {
+            // repeat fetch in case previous creation failed due to variable already concurrently created
             getProp().catch((secondErr) => {
                 throw secondErr;
             });
@@ -19,6 +24,7 @@ const useEntityProperty = ({ entityManager, defaultRetryCount = 2 }) => {
         let success = false;
         let tryCounts = 0;
         const attempt = async () => setPropValue(await entityManager.update(valueUpdate));
+        // initial update attempt + up to <retryCount> retries if update unsuccessful
         while (!success && tryCounts <= retryCount) {
             try {
                 tryCounts++;
@@ -27,7 +33,7 @@ const useEntityProperty = ({ entityManager, defaultRetryCount = 2 }) => {
             }
             catch (err) {
                 if (tryCounts > retryCount) {
-                    console.error(err);
+                    console.error(err); // eslint-disable-line no-console
                 }
             }
         }

package/out/hooks/useForm.js

@@ -6,18 +6,32 @@ const react_1 = require("react");
 const react_hook_form_1 = require("react-hook-form");
 const get_1 = tslib_1.__importDefault(require("lodash/get"));
 function useForm(props = {}) {
+    // Generate an id to prevent clashes with other forms on the page
     const id = (0, react_1.useId)();
     const getFieldId = (fieldName) => {
         return `form-${id}-${fieldName}`;
     };
-    const { register, formState, handleSubmit, setValue, getValues, trigger, clearErrors } = (0, react_hook_form_1.useForm)({
+    const { register, formState, 
+    // watch, disabling for the time being as can be expensive for performance
+    handleSubmit, setValue, getValues, trigger, clearErrors
+    // Only allow for defaultValues in props for the timebeing
+     } = (0, react_hook_form_1.useForm)({
         defaultValues: props.defaultValues,
         mode: 'onBlur',
         reValidateMode: 'onChange'
     });
     const defaultValues = props?.defaultValues;
     const forgeFormRegister = (fieldName, options) => {
+        /**
+         * Removed:
+         * - ref cannot be serialised and passed through the run time
+         * - removed required to stop the default browser validation pop up
+         * - UI Kit 2 components take `isDisabled` instead of `disabled`
+         * - `onChange` is modified to handle our controlled components as refs cannot be used
+         */
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         const { onChange, ref, required, disabled, onBlur, ...rest } = register(fieldName, {
+            // Only permitting the below as they've been tested and confirmed working
             required: options?.required,
             disabled: options?.disabled,
             maxLength: options?.maxLength,
@@ -29,6 +43,8 @@ function useForm(props = {}) {
         });
         const additionalProps = {};
         if (defaultValues) {
+            // only checkbox and toggle have boolean vals.
+            // Typically this is handled by the ref obj but we need to manage the default values ourselves here
             if (typeof (0, get_1.default)(defaultValues, fieldName) === 'boolean') {
                 additionalProps.defaultChecked = (0, get_1.default)(defaultValues, fieldName);
             }
@@ -39,11 +55,14 @@ function useForm(props = {}) {
         const isError = !!(0, get_1.default)(formState, `errors["${fieldName}"]`);
         const onChangeOptions = {
             shouldDirty: true,
+            // revalidate on change if the field has been touched(blurred) or if the form has been submitted previously
             shouldValidate: formState.submitCount > 0 || !!(0, get_1.default)(formState, `touchedFields["${fieldName}"]`)
         };
         return {
             ...rest,
             onChange: (event) => {
+                // onChange is modified here to handle our controlled components as refs cannot be used
+                // handles Checkbox and Toggle
                 if (event?.target?.type === 'checkbox') {
                     return Promise.resolve(setValue(fieldName, event.target.checked, onChangeOptions));
                 }
@@ -51,9 +70,12 @@ function useForm(props = {}) {
                     return Promise.resolve(setValue(fieldName, event.target.value, onChangeOptions));
                 }
                 else {
+                    // handles onChange arguments where the value is passed instead of an event object
                     return Promise.resolve(setValue(fieldName, event, onChangeOptions));
                 }
             },
+            // The onBlur event from `register` is unintentionally setting the value to `undefined` when the field is blurred.
+            // Replacing the onBlur event here to prevent this behaviour.
             onBlur: () => {
                 return Promise.resolve(trigger(fieldName));
             },

package/out/hooks/useIssueProperty.d.ts

@@ -1,2 +1,11 @@
+/**
+ * This function manages the properties of a Jira issue where the app is installed
+ * @param propertyKey Name (key) of the property
+ * @param initValue Default value if it did not exist previously
+ * @returns An array with 3 items:
+ *  1. Current value of the property.
+ *  2. A function to update the property value (with another value or an updater function). If a <retryCount> is given and an initial update fails, it automatically tries to update for another <retryCount> times (default 0).
+ *  3. A function to delete the property.
+ */
 export declare const useIssueProperty: <PropValue>(propertyKey: string, initValue: PropValue) => readonly [any, (valueUpdate: any, retryCount?: number) => Promise<void>, () => Promise<void>];
 //# sourceMappingURL=useIssueProperty.d.ts.map

package/out/hooks/useIssueProperty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useIssueProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useIssueProperty.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,gBAAgB,2BAA4B,MAAM,wHAW9D,CAAC"}
+{"version":3,"file":"useIssueProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useIssueProperty.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,2BAA4B,MAAM,wHAW9D,CAAC"}

package/out/hooks/useIssueProperty.js

@@ -4,12 +4,21 @@ exports.useIssueProperty = void 0;
 const react_1 = require("react");
 const jiraEntity_1 = require("./jiraEntity");
 const useEntityProperty_1 = require("./useEntityProperty");
+/**
+ * This function manages the properties of a Jira issue where the app is installed
+ * @param propertyKey Name (key) of the property
+ * @param initValue Default value if it did not exist previously
+ * @returns An array with 3 items:
+ *  1. Current value of the property.
+ *  2. A function to update the property value (with another value or an updater function). If a <retryCount> is given and an initial update fails, it automatically tries to update for another <retryCount> times (default 0).
+ *  3. A function to delete the property.
+ */
 const useIssueProperty = (propertyKey, initValue) => {
     const entityManager = (0, react_1.useMemo)(() => (0, jiraEntity_1.jiraIssuePropsManager)({
         entityType: 'Issue',
         origPropertyKey: propertyKey,
         initValue
     }), []);
-    return (0, useEntityProperty_1.useEntityProperty)({ entityManager, defaultRetryCount: 0 });
+    return (0, useEntityProperty_1.useEntityProperty)({ entityManager, defaultRetryCount: 0 }); // no update retries needed for issue properties
 };
 exports.useIssueProperty = useIssueProperty;

package/out/hooks/useSpaceProperty.d.ts

@@ -1,2 +1,11 @@
+/**
+ * This function manages the space properties of a Confluence space where the app is installed.
+ * @param propertyKey Name (key) of the property
+ * @param initValue Default value if it did not exist previously
+ * @returns An array with 3 items:
+ *  1. Current value of the property.
+ *  2. A function to update the property value (with another value or an updater function). If an initial update fails, it automatically tries to update for another <retryCount> times (default 2).
+ * 3. A function to delete the property.
+ */
 export declare const useSpaceProperty: <PropValue>(propertyKey: string, initValue: PropValue) => readonly [PropValue | undefined, (valueUpdate: import("./types/entityProps").ValueUpdate<PropValue>, retryCount?: number) => Promise<void>, () => Promise<void>];
 //# sourceMappingURL=useSpaceProperty.d.ts.map

package/out/hooks/useSpaceProperty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSpaceProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useSpaceProperty.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,gBAAgB,2BAA4B,MAAM,2LAW9D,CAAC"}
+{"version":3,"file":"useSpaceProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useSpaceProperty.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,2BAA4B,MAAM,2LAW9D,CAAC"}