@contentful/react-apps-toolkit 0.5.11 → 0.7.0

package/README.md

@@ -1,12 +1,8 @@
-# In development
-
-This library is still in development and should not be used in production.
-
 # React Toolkit for Contentful Apps
 
-This package consists of helpers and hooks to create a Contentful app with React.
+React Hooks for the App Framework offer a simple way to bring frequently needed functionality into your react based [Contentful apps](/developers/docs/extensibility/app-framework/).
 
-This library can be used in apps created by [`create-contentful-app`](https://www.npmjs.com/package/create-contentful-app), but can also be used with any other React app using Contentful's [App SDK](https://www.npmjs.com/package/@contentful/app-sdk).
+They can be used in apps created with [`create-contentful-app`](https://www.npmjs.com/package/@contentful/create-contentful-app), as well as any other React app using Contentful's [App SDK](https://www.npmjs.com/package/@contentful/app-sdk).
 
 ## Installation
 
@@ -20,52 +16,115 @@ yarn add @contentful/react-apps-toolkit
 
 The following hooks and utilities are exported from the package:
 
-### `useSDK`
-
-This hook returns the App SDK.
+### SDKProvider
 
-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.
+The `SDKProvider` is a wrapper component, which automatically makes the Contentful [App SDK](https://www.npmjs.com/package/@contentful/app-sdk) available to any child components using React Context. To use any of the hooks contained in this package, they must be wrapped in the `<SDKProvider>`, because all of the hooks depend on the App SDK.
 
-Here is an example of how you can use it:
+Usage:
 
 ```tsx
-import { useSDK } from '@contentful/react-apps-toolkit'
+import { SDKProvider, useSDK } from '@contentful/react-apps-toolkit';
 
-function App() {
+function ChildComponentUsingHook() {
   const sdk = useSDK<FieldExtensionSDK>();
 
-  return <>App Id: {sdk.ids.app}</>
+  return <>App Id: {sdk.ids.app}</>;
 }
 
+function App() {
+  return (
+    <SDKProvider>
+      <ChildComponentUsingHook />
+    </SDKProvider>
+  );
+}
 ```
 
-### `useCMA`
+### useSDK
+
+`useSDK` returns an instance of the Contentful [App SDK](https://www.npmjs.com/package/@contentful/app-sdk).
 
-Returns an initialized [plain client](https://github.com/contentful/contentful-management.js/#alternative-plain-api) for the Contentful Management API, which can immediately be used to communicate with the rest of your Contentful space. [Contentful Management API docs](https://www.contentful.com/developers/docs/references/content-management-api/).
+It must be wrapped it within the `SDKProvider`, otherwise, it will throw an error.
 
+Usage:
 
 ```tsx
-import { useCMA } from '@contentful/react-apps-toolkit'
+import { SDKProvider, useSDK } from '@contentful/react-apps-toolkit';
+
+function ComponentUsingSDK() {
+  const sdk = useSDK<FieldExtensionSDK>();
+
+  return <>App Id: {sdk.ids.app}</>;
+}
 
 function App() {
+  return (
+    <SDKProvider>
+      <ChildComponentUsingSDK />
+    </SDKProvider>
+  );
+}
+```
+
+### useCMA
+
+`useCMA` returns an initialized [client for the Contentful Management API](https://www.npmjs.com/package/contentful-management). This can be used immediately to communicate with the environment the app is rendered in. [Contentful Management API docs](/developers/docs/references/content-management-api/).
+
+**Note**: The CMA client instance returned by this hook is automatically scoped to the contentful space and environment in which it is called.
+
+Usage:
+
+```tsx
+import { SDKProvider, useCMA } from '@contentful/react-apps-toolkit';
+
+function ComponentUsingCMA() {
   const cma = useCMA();
+  const [entries, setEntries] = useState();
 
   useEffect(() => {
-    cma.entry.get({ entryId: '2VO9yOaeSyAFA19e649SxG' }).then((entry) => {
-      console.log(entry);
-    });
-  }, []);
+    cma.entries.getMany().then(setEntries);
+  }, [cma]);
 
-  return <>Hello world!</>
+  return <>{entries?.length}</>;
 }
 
+function App() {
+  return (
+    <SDKProvider>
+      <ComponentUsingCMA />
+    </SDKProvider>
+  );
+}
 ```
 
-#### SDKProvider
+### useFieldValue
+
+`useFieldValue` provides the current value, and a setter function for updating the current value, of a given field in Contentful. If used in the [field location](/developers/docs/extensibility/app-framework/locations/#entry-field), it will initialize using the current field id by default.
+
+If used in the [entry sidebar location](/developers/docs/extensibility/app-framework/locations/#entry-sidebar), or the [entry editor location](/developers/docs/extensibility/app-framework/locations/#entry-editor), it must be passed a field ID to initialize.
+
+`useFieldValue` also optionally accepts a locale, if the field has multiple locales. If no locale is passed, it will use the environment's default locale.
+
+Usage:
 
-Wrapper component, which makes the Apps SDK available to children via React Context. To use any of the hooks contained in this package, an application must be wrapped in the SDK provider, as all hooks depend on the Apps SDK.
+```tsx
+import { SDKProvider, useFieldValue } from '@contentful/react-apps-toolkit';
+
+function ComponentUsingFieldValue() {
+  const [value, setValue] = useFieldValue('slug', 'en-US');
+
+  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
+}
+
+function App() {
+  return (
+    <SDKProvider>
+      <ComponentUsingFieldValue />
+    </SDKProvider>
+  );
+}
+```
 
 ### Resources
 
-- [Create Contentful App](https://www.contentful.com/developers/docs/extensibility/app-framework/create-contentful-app/)
+- [create-contentful-app](https://www.npmjs.com/package/create-contentful-app): A starter that makes it easy to bootstrap apps for Contentful.

package/dist/SDKProvider.d.ts

@@ -1,6 +1,6 @@
-import React, { FC, ReactElement } from 'react';
 import { KnownSDK } from '@contentful/app-sdk';
-export declare const SDKContext: React.Context<{
+import { FC, ReactElement } from 'react';
+export declare const SDKContext: import("react").Context<{
     sdk: KnownSDK | null;
 }>;
 interface SDKProviderProps {

package/dist/SDKProvider.js

@@ -10,23 +10,20 @@ var __assign = (this && this.__assign) || function () {
     };
     return __assign.apply(this, arguments);
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDKProvider = exports.SDKContext = void 0;
 var jsx_runtime_1 = require("react/jsx-runtime");
-var react_1 = __importDefault(require("react"));
 var app_sdk_1 = require("@contentful/app-sdk");
-exports.SDKContext = react_1.default.createContext({ sdk: null });
+var react_1 = require("react");
+exports.SDKContext = (0, react_1.createContext)({ sdk: null });
 var DELAY_TIMEOUT = 4 * 1000;
 /**
  * The Component providing the AppSdk, the useSDK hook can only be used within this Provider
  * @param props.loading an optional loading element that gets rendered while initializing the app
  */
 var SDKProvider = function (props) {
-    var _a = react_1.default.useState(), sdk = _a[0], setSDK = _a[1];
-    react_1.default.useEffect(function () {
+    var _a = (0, react_1.useState)(), sdk = _a[0], setSDK = _a[1];
+    (0, react_1.useEffect)(function () {
         var timeout = window.setTimeout(function () {
             console.warn("Your app is taking longer than expected to initialize. If you think this is an error with Contentful's App SDK, let us know: https://github.com/contentful/ui-extensions-sdk/issues");
         }, DELAY_TIMEOUT);

package/dist/useFieldValue.d.ts

@@ -1,6 +1,7 @@
+import { SerializedJSONValue } from '@contentful/app-sdk';
 export declare type UseFieldValueReturnValue<Value = unknown> = [
     value: Value | undefined,
-    setValue: (newValue: Value | undefined) => Promise<void>
+    setValue: (newValue: Value | undefined) => Promise<SerializedJSONValue | undefined>
 ];
 /**
  * Returns field value and a function to update it.

package/dist/useFieldValue.js

@@ -61,9 +61,7 @@ function useFieldValue(fieldId, locale) {
                 case 0:
                     setValue(newValue);
                     return [4 /*yield*/, entryFieldApi.setValue(newValue, localeWithDefault)];
-                case 1:
-                    _a.sent();
-                    return [2 /*return*/];
+                case 1: return [2 /*return*/, _a.sent()];
             }
         });
     }); }, [entryFieldApi, localeWithDefault]);

package/dist/useFieldValue.spec.js

@@ -77,7 +77,11 @@ var useSDKMock = useSDK_1.useSDK;
 beforeEach(function () {
     jest.resetAllMocks();
     mockSDK.entry.fields.fieldId.onValueChanged.mockImplementation(function () { return function () { }; });
+    mockSDK.entry.fields.fieldId.setValue.mockImplementation(function () { return Promise.resolve('return value'); });
     mockSDK.entry.fields.otherFieldId.onValueChanged.mockImplementation(function () { return function () { }; });
+    mockSDK.entry.fields.otherFieldId.setValue.mockImplementation(function () {
+        return Promise.resolve('other return value');
+    });
 });
 describe('useFieldValue', function () {
     describe('throws error', function () {
@@ -120,7 +124,16 @@ describe('useFieldValue', function () {
         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 0: return [4 /*yield*/, (0, react_hooks_1.act)(function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0: return [4 /*yield*/, result.current[1]('new value')];
+                                    case 1:
+                                        _a.sent();
+                                        return [2 /*return*/];
+                                }
+                            });
+                        }); })];
                     case 1:
                         _a.sent();
                         expect(result.current[0]).toBe('new value');
@@ -135,6 +148,27 @@ describe('useFieldValue', function () {
             (0, react_hooks_1.act)(function () { return calls[0][1]('new value'); });
             expect(result.current[0]).toBe('new value');
         });
+        it('returns the updated value', function () { return __awaiter(void 0, void 0, void 0, function () {
+            var returnedValue;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, react_hooks_1.act)(function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0: return [4 /*yield*/, result.current[1]('new value')];
+                                    case 1:
+                                        returnedValue = _a.sent();
+                                        return [2 /*return*/];
+                                }
+                            });
+                        }); })];
+                    case 1:
+                        _a.sent();
+                        expect(returnedValue).toBe('return value');
+                        return [2 /*return*/];
+                }
+            });
+        }); });
     });
     describe('with `fieldId`', function () {
         var result;
@@ -149,7 +183,16 @@ describe('useFieldValue', function () {
         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 0: return [4 /*yield*/, (0, react_hooks_1.act)(function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0: return [4 /*yield*/, result.current[1]('new value')];
+                                    case 1:
+                                        _a.sent();
+                                        return [2 /*return*/];
+                                }
+                            });
+                        }); })];
                     case 1:
                         _a.sent();
                         expect(result.current[0]).toBe('new value');
@@ -178,7 +221,16 @@ describe('useFieldValue', function () {
         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 0: return [4 /*yield*/, (0, react_hooks_1.act)(function () { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0: return [4 /*yield*/, result.current[1]('new value')];
+                                    case 1:
+                                        _a.sent();
+                                        return [2 /*return*/];
+                                }
+                            });
+                        }); })];
                     case 1:
                         _a.sent();
                         expect(result.current[0]).toBe('new value');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/react-apps-toolkit",
-  "version": "0.5.11",
+  "version": "0.7.0",
   "description": "Toolkit for building a Contentful app in React",
   "keywords": [],
   "author": "Contentful GmbH",
@@ -40,6 +40,7 @@
     "@types/react": "^17.0.39",
     "jest": "^27.5.0",
     "react": "^17.0.2",
+    "react-dom": "17.0.2",
     "ts-jest": "^27.1.3",
     "typescript": "^4.5.5"
   },
@@ -50,5 +51,5 @@
     "@contentful/app-sdk": "^4.0.0",
     "contentful-management": ">=7.30.0"
   },
-  "gitHead": "61e3382ccad0a4bfb72625f5681271667e15acd6"
+  "gitHead": "9b4d1a392a1018d6f11dd6b9589a313854173fd3"
 }