@contentful/react-apps-toolkit 0.4.2 → 0.5.2

package/README.md

@@ -18,7 +18,26 @@ yarn add @contentful/react-apps-toolkit
 
 ## Available features
 
-The following hooks and utilities are exported from the package: Nothing
+The following hooks and utilities are exported from the package:
+
+### `useSDK`
+
+This hook returns the App SDK.
+
+The only requirement for using it is that the component that uses it is wrapped within the `SDKProvider`.
+If it is not, the hook will throw an error.
+
+Here is an example of how you can use it:
+
+```tsx
+function App() {
+  const sdk = useSDK<FieldExtensionSDK>();
+
+  return <>App Id: {sdk.ids.app}</>
+}
+
+```
+
 
 #### SDKProvider
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export * from './useSDK';
 export * from './SDKProvider';
 export * from './useCMA';
+export * from './useFieldValue';
+export * from './useSDK';

package/dist/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./useSDK"), exports);
 __exportStar(require("./SDKProvider"), exports);
 __exportStar(require("./useCMA"), exports);
+__exportStar(require("./useFieldValue"), exports);
+__exportStar(require("./useSDK"), exports);

package/dist/useFieldValue.d.ts

@@ -0,0 +1,14 @@
+export declare type UseFieldValueReturnValue<Value = unknown> = [
+    value: Value,
+    setValue: (newValue: Value) => Promise<void>
+];
+/**
+ * Returns field value and a function to update it.
+ * Must be wrapped by SDKProvider.
+ * Can only be used when app is rendered in field, sidebar or entry editor location.
+ *
+ * @param {string=} fieldId Id of the field to read and update. Can be omitted when app is rendered in field location.
+ * @param {string=} locale Locale to read and update. When omitted, default locale is used.
+ * @returns {UseFieldValueReturnValue} Field value, function to update it
+ */
+export declare function useFieldValue<Value = unknown>(fieldId?: string, locale?: string): UseFieldValueReturnValue<Value>;

package/dist/useFieldValue.js

@@ -0,0 +1,86 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFieldValue = void 0;
+var react_1 = require("react");
+var useSDK_1 = require("./useSDK");
+/**
+ * Returns field value and a function to update it.
+ * Must be wrapped by SDKProvider.
+ * Can only be used when app is rendered in field, sidebar or entry editor location.
+ *
+ * @param {string=} fieldId Id of the field to read and update. Can be omitted when app is rendered in field location.
+ * @param {string=} locale Locale to read and update. When omitted, default locale is used.
+ * @returns {UseFieldValueReturnValue} Field value, function to update it
+ */
+function useFieldValue(fieldId, locale) {
+    var _this = this;
+    var sdk = (0, useSDK_1.useSDK)();
+    var entryFieldApi = (0, react_1.useMemo)(function () { return getEntryFieldApi(sdk, fieldId); }, [sdk, fieldId]);
+    var localeWithDefault = locale !== null && locale !== void 0 ? locale : sdk.locales.default;
+    var _a = (0, react_1.useState)(entryFieldApi.getValue(localeWithDefault)), value = _a[0], setValue = _a[1];
+    (0, react_1.useEffect)(function () { return entryFieldApi.onValueChanged(localeWithDefault, setValue); }, [entryFieldApi, localeWithDefault]);
+    var updateValue = (0, react_1.useCallback)(function (newValue) { return __awaiter(_this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    setValue(newValue);
+                    return [4 /*yield*/, entryFieldApi.setValue(newValue, localeWithDefault)];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); }, [entryFieldApi, localeWithDefault]);
+    return [value, updateValue];
+}
+exports.useFieldValue = useFieldValue;
+function getEntryFieldApi(sdk, fieldId) {
+    if (!('entry' in sdk)) {
+        throw new Error('`useFieldValue` can only be used in field, sidebar or entry editor location.');
+    }
+    var fieldIdWithDefault = fieldId !== null && fieldId !== void 0 ? fieldId : ('field' in sdk ? sdk.field.id : undefined);
+    if (!fieldIdWithDefault) {
+        throw new Error('Missing `fieldId`. The `fieldId` can only be omitted when your app is renderd in field location.');
+    }
+    var field = sdk.entry.fields[fieldIdWithDefault];
+    if (!field) {
+        throw new Error("Invalid `fieldId`. The current entry does not have a field \"".concat(fieldIdWithDefault, "\"."));
+    }
+    return field;
+}

package/dist/useFieldValue.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/useFieldValue.spec.js

@@ -0,0 +1,197 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var react_hooks_1 = require("@testing-library/react-hooks");
+var useFieldValue_1 = require("./useFieldValue");
+var useSDK_1 = require("./useSDK");
+var mockSDK = {
+    field: {
+        id: 'fieldId',
+    },
+    locales: {
+        default: 'defaultLocale',
+    },
+    entry: {
+        fields: {
+            fieldId: {
+                getValue: function (locale) { return "fieldId ".concat(locale, " value"); },
+                onValueChanged: jest.fn(),
+                setValue: jest.fn(),
+            },
+            otherFieldId: {
+                getValue: function (locale) { return "otherFieldId ".concat(locale, " value"); },
+                onValueChanged: jest.fn(),
+                setValue: jest.fn(),
+            },
+        },
+    },
+};
+jest.mock('./useSDK', function () { return (__assign(__assign({}, jest.requireActual('./useSDK')), { useSDK: jest.fn() })); });
+var useSDKMock = useSDK_1.useSDK;
+beforeEach(function () {
+    jest.resetAllMocks();
+    mockSDK.entry.fields.fieldId.onValueChanged.mockImplementation(function () { return function () { }; });
+    mockSDK.entry.fields.otherFieldId.onValueChanged.mockImplementation(function () { return function () { }; });
+});
+describe('useFieldValue', function () {
+    describe('throws error', function () {
+        it('when rendered in wrong location', function () {
+            useSDKMock.mockImplementation(function () { return ({}); });
+            var result = (0, react_hooks_1.renderHook)(function () { return (0, useFieldValue_1.useFieldValue)(); }).result;
+            expect(function () {
+                expect(result.current).not.toBe(undefined);
+            }).toThrowErrorMatchingInlineSnapshot("\"`useFieldValue` can only be used in field, sidebar or entry editor location.\"");
+        });
+        it('when rendered omitting `fieldId` outside of field location', function () {
+            // @ts-expect-error
+            useSDKMock.mockImplementation(function () { return ({
+                entry: mockSDK.entry,
+            }); });
+            var result = (0, react_hooks_1.renderHook)(function () { return (0, useFieldValue_1.useFieldValue)(); }).result;
+            expect(function () {
+                expect(result.current).not.toBe(undefined);
+            }).toThrowErrorMatchingInlineSnapshot("\"Missing `fieldId`. The `fieldId` can only be omitted when your app is renderd in field location.\"");
+        });
+        it('when providing unknown `fieldId`', function () {
+            // @ts-expect-error
+            useSDKMock.mockImplementation(function () { return mockSDK; });
+            var result = (0, react_hooks_1.renderHook)(function () { return (0, useFieldValue_1.useFieldValue)('unknownFieldId'); }).result;
+            expect(function () {
+                expect(result.current).not.toBe(undefined);
+            }).toThrowErrorMatchingInlineSnapshot("\"Invalid `fieldId`. The current entry does not have a field \\\"unknownFieldId\\\".\"");
+        });
+    });
+    describe('with no params', function () {
+        var result;
+        beforeEach(function () {
+            // @ts-expect-error
+            useSDKMock.mockImplementation(function () { return mockSDK; });
+            result = (0, react_hooks_1.renderHook)(function () { return (0, useFieldValue_1.useFieldValue)(); }).result;
+        });
+        it('returns initial value', function () {
+            expect(result.current[0]).toBe('fieldId defaultLocale value');
+        });
+        it('updates value', function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, react_hooks_1.act)(function () { return result.current[1]('new value'); })];
+                    case 1:
+                        _a.sent();
+                        expect(result.current[0]).toBe('new value');
+                        expect(mockSDK.entry.fields['fieldId'].setValue).toHaveBeenCalledWith('new value', 'defaultLocale');
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        it('updates value when `onValueChanged` is called', function () {
+            var calls = mockSDK.entry.fields.fieldId.onValueChanged.mock.calls;
+            expect(calls[0][0]).toBe('defaultLocale');
+            (0, react_hooks_1.act)(function () { return calls[0][1]('new value'); });
+            expect(result.current[0]).toBe('new value');
+        });
+    });
+    describe('with `fieldId`', function () {
+        var result;
+        beforeEach(function () {
+            // @ts-expect-error
+            useSDKMock.mockImplementation(function () { return mockSDK; });
+            result = (0, react_hooks_1.renderHook)(function () { return (0, useFieldValue_1.useFieldValue)('otherFieldId'); }).result;
+        });
+        it('returns initial value', function () {
+            expect(result.current[0]).toBe('otherFieldId defaultLocale value');
+        });
+        it('updates value', function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, react_hooks_1.act)(function () { return result.current[1]('new value'); })];
+                    case 1:
+                        _a.sent();
+                        expect(result.current[0]).toBe('new value');
+                        expect(mockSDK.entry.fields['otherFieldId'].setValue).toHaveBeenCalledWith('new value', 'defaultLocale');
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        it('updates value when `onValueChanged` is called', function () {
+            var calls = mockSDK.entry.fields.otherFieldId.onValueChanged.mock.calls;
+            expect(calls[0][0]).toBe('defaultLocale');
+            (0, react_hooks_1.act)(function () { return calls[0][1]('new value'); });
+            expect(result.current[0]).toBe('new value');
+        });
+    });
+    describe('with `locale`', function () {
+        var result;
+        beforeEach(function () {
+            // @ts-expect-error
+            useSDKMock.mockImplementation(function () { return mockSDK; });
+            result = (0, react_hooks_1.renderHook)(function () { return (0, useFieldValue_1.useFieldValue)('fieldId', 'locale'); }).result;
+        });
+        it('returns initial value', function () {
+            expect(result.current[0]).toBe('fieldId locale value');
+        });
+        it('updates value', function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, react_hooks_1.act)(function () { return result.current[1]('new value'); })];
+                    case 1:
+                        _a.sent();
+                        expect(result.current[0]).toBe('new value');
+                        expect(mockSDK.entry.fields['fieldId'].setValue).toHaveBeenCalledWith('new value', 'locale');
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        it('updates value when `onValueChanged` is called', function () {
+            var calls = mockSDK.entry.fields.fieldId.onValueChanged.mock.calls;
+            expect(calls[0][0]).toBe('locale');
+            (0, react_hooks_1.act)(function () { return calls[0][1]('new value'); });
+            expect(result.current[0]).toBe('new value');
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/react-apps-toolkit",
-  "version": "0.4.2",
+  "version": "0.5.2",
   "description": "Toolkit for building a Contentful app in React",
   "keywords": [],
   "author": "Contentful GmbH",
@@ -50,5 +50,5 @@
     "@contentful/app-sdk": "^4.0.0",
     "contentful-management": ">=7.30.0"
   },
-  "gitHead": "07fa91924433749cd6946874600837e42b25e2d5"
+  "gitHead": "174ac57f86e1e9bde1594fa444ba1fd59f5ebe91"
 }