[react] feat: Added docs for hooks/useControl

packages/react/components/Account/Control.mjs

@@ -44,7 +44,7 @@ const strings = {
  */
 export const Control = ({ welcome = false }) => {
   // Hooks
-  const { control, updateControl } = useControl()
+  const { control, setControl } = useControl()
 
   // Helper to get the link to the next onboarding step
   const nextHref = welcome
@@ -69,7 +69,7 @@ export const Control = ({ welcome = false }) => {
           desc: controlDesc[val].desc,
         }))}
         current={control}
-        update={updateControl}
+        update={setControl}
       />
       {welcome ? (
         <>

packages/react/hooks/useControl/index.mjs

@@ -17,16 +17,25 @@ export const useControl = () => {
   const { setLoadingStatus } = useContext(LoadingStatusContext)
 
   // State
-  const [control, setControl] = useState(account.control)
+  const [control, __setControl] = useState(account.control)
 
-  // Method to update the control setting
+  /*
+   * Legacy method to update the control setting
+   * Deprecated because its naming is inconsistent with other hooks
+   */
   const updateControl = async (newControl) => {
+    console.warn('The updateControl method is deprecated. Use setControl instead.')
+    return setControl(newControl)
+  }
+
+  // Method to set the control setting
+  const setControl = async (newControl) => {
     if (newControl !== control) {
       if (token) {
         setLoadingStatus([true, 'Updating preferences'])
         const [status, body] = await backend.updateAccount({ control: newControl })
         if (status === 200) {
-          setControl(newControl)
+          __setControl(newControl)
           setAccount(body.account)
           setLoadingStatus([true, 'Preferences updated', true, true])
         } else
@@ -37,10 +46,10 @@ export const useControl = () => {
          * So this ensures control is always available, even if people are not authenticated
          */
         setAccount({ ...account, control: newControl })
-        setControl(newControl)
+        __setControl(newControl)
       }
     }
   }
 
-  return { control, updateControl }
+  return { control, setControl, updateControl }
 }

sites/dev/docs/reference/packages/react/hooks/usebackend/readme.mdx

@@ -2,7 +2,6 @@
 title: useBackend
 ---
 
-
 import { DocusaurusDoc } from '@freesewing/react/components/Docusaurus'
 import { MiniTip } from '@freesewing/react/components/Mini'
 import { Popout } from '@freesewing/react/components/Popout'

sites/dev/docs/reference/packages/react/hooks/usecontrol/readme.mdx

@@ -2,6 +2,56 @@
 title: useControl
 ---
 
-:::note
-This page is yet to be created
-:::
+import { DocusaurusDoc } from '@freesewing/react/components/Docusaurus'
+import { MiniTip } from '@freesewing/react/components/Mini'
+import { Popout } from '@freesewing/react/components/Popout'
+
+<DocusaurusDoc>
+
+The **useControl** hook provides access to the control setting of a FreeSewing user.
+Use this hook whether you have a UI element that should be hidden or shown
+based on the control setting.
+
+<Popout type="tip" title="useControl vs useAccount">
+  The **useControl** hook guarantees that a control value will always be available, even if no user
+  is authenticated. As such, it is recommended to use this rather than the
+  [useAccount](/reference/packages/react/hooks/useaccount/) hook when all you need is a control
+  value, and no access to the user account.
+</Popout>
+
+## Example
+
+```js
+import { useControl } from '@freesewing/react/hooks/useControl'
+
+const MyComponent = () => {
+  control,
+  setControl,
+} = useControl()
+
+  // ...
+}
+```
+
+## Return value
+
+Calling the hook returns an object with the following properties which are all methods:
+
+- [control](#control)
+- [setControl](#setControl)
+
+### control
+
+The control value.
+
+### setControl
+
+A method to set the new control value.
+
+```js
+function setControl (
+  Number control // The new control value to set
+)
+```
+
+</DocusaurusDoc>