@contentful/react-apps-toolkit 0.6.0 → 0.6.1

package/README.md

@@ -4,9 +4,9 @@ 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 +20,115 @@ yarn add @contentful/react-apps-toolkit
 
 The following hooks and utilities are exported from the package:
 
-### `useSDK`
+### SDKProvider
 
-This hook returns the App SDK.
+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.
 
-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:
+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
 
-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/).
+`useSDK` returns an instance of the Contentful [App SDK](https://www.npmjs.com/package/@contentful/app-sdk).
 
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/react-apps-toolkit",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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-test-renderer": "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": "a279a7b92f12e6792e4c76d86a3277006143bff0"
+  "gitHead": "92d4d8ae34401669f4548d408f7168837a30a539"
 }