@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/adminide-modules/preferences/useSettingsLoader.md

@@ -0,0 +1,248 @@
+---
+meta:
+    title: Use Setting Loader
+    description: Use Setting Loader
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Use Setting Loader...
+headers:
+    Cache-Control: no-cache
+---
+
+### **Documentation: `useSettingsLoader` Hook**
+
+The `useSettingsLoader` hook is a utility for fetching and updating organizational and resource-level configurations from an Apollo Client query in a Remix application. It provides an easy way to manage configurations with the ability to update them and automatically refetch them when needed.
+
+---
+
+### **Hook Signature**
+
+```typescript
+export const useSettingsLoader = <K = IConfigurationsFlattenedKeys, R = IPreferences>(
+    settingsVariable: ISettingsLoaderVariable<K>,
+): IResponse<K>
+```
+
+### **Parameters**
+
+- `settingsVariable: ISettingsLoaderVariable<K>`:
+    - **configKey**: The key used to identify the configuration to fetch.
+    - **skip** (optional): A flag to skip querying or fetching the configuration when set to `true`.
+
+### **Return Value**
+
+The hook returns an object of type `IResponse<K>` with the following properties:
+
+- **data**: The current configuration value (`string | number | boolean`) corresponding to the `configKey`. It could come from either the initial data provided by the Remix loader or the refetched data from Apollo Client.
+- **loading**: A `boolean` indicating whether the hook is in a loading state.
+- **error**: Any error that occurred during the fetching or updating of configurations.
+- **preferencesInput**: Input preferences related to the configuration, retrieved from the Remix loader's context.
+- **updateConfiguration**: A function that allows updating the configuration value for a given key. After successfully updating, it refetches the configuration from the server.
+
+### Prerequisites
+
+1. **Apollo Client Setup**: Your project should be configured with Apollo Client to handle GraphQL queries and mutations.
+2. **Route Configuration**: In `compute.ts` of the specific route should have `configurations` with optional `resourceParams`. Please check the docs under the remix section for more information.
+
+---
+
+### `useSettingsLoader` Hook Usage Guide
+
+The `useSettingsLoader` hook is a utility for managing configuration settings in a React application, particularly in scenarios where initial configurations are loaded through a data loader (like Remix's `useLoaderData`), and you want to handle updates or refetches using Apollo Client.
+
+Here’s a step-by-step guide on how to use the `useSettingsLoader` hook effectively in your application.
+
+---
+
+### Prerequisites
+
+1. **Apollo Client Setup**: Your project should be configured with Apollo Client to handle GraphQL queries and mutations.
+2. **Remix Data Loader**: You'll use Remix's `useLoaderData` to fetch the initial configurations from the server during route rendering.
+3. **React Environment**: Ensure that your application is wrapped in an `ApolloProvider` and `MemoryRouter` (for testing), or another appropriate router setup during runtime.
+
+---
+
+### Basic Usage
+
+#### 1. **Loading Initial Configuration**
+
+The `useSettingsLoader` hook is designed to first retrieve configuration data from Remix’s `useLoaderData`. You need to pass a `configKey` to identify which configuration value you are targeting.
+
+Here’s how you can use it in a basic component:
+
+```tsx
+import { useSettingsLoader } from './hooks/useSettingsLoader';
+
+const NotificationSettings = () => {
+    const { data, loading, error } = useSettingsLoader({
+        configKey: 'account.notification.primaryEmail',
+    });
+
+    if (loading) {
+        return <div>Loading...</div>;
+    }
+
+    if (error) {
+        return <div>Error: {error.message}</div>;
+    }
+
+    return <div>Notification Email: {data}</div>;
+};
+
+export default NotificationSettings;
+```
+
+- **`configKey`**: This is the key used to fetch a specific configuration. In the above example, we are retrieving the `account.notification.primaryEmail` value.
+- **`data`**: The configuration value returned by the hook. It will either come from the Remix loader (initially) or be refetched via Apollo Client.
+- **`loading`**: A boolean indicating whether the configuration is currently being fetched.
+- **`error`**: If any errors occur during the data fetching process, they will be captured here.
+
+#### 2. **Updating the Configuration**
+
+The `useSettingsLoader` hook also provides an `updateConfiguration` function, which you can use to update the configuration and trigger a refetch of the data.
+
+Here’s an example:
+
+```tsx
+const NotificationSettings = () => {
+    const { data, updateConfiguration } = useSettingsLoader({
+        configKey: 'account.notification.primaryEmail',
+    });
+
+    const handleUpdate = async () => {
+        await updateConfiguration({
+            updateKey: 'account.notification.primaryEmail',
+            value: 'new-email@example.com',
+        });
+    };
+
+    return (
+        <div>
+            <p>Notification Email: {data}</p>
+            <button onClick={handleUpdate}>Update Email</button>
+        </div>
+    );
+};
+```
+
+- **`updateConfiguration`**: This function accepts an object with parameters:
+    - `updateKey`: The key for the configuration to update (optional if it's the same as the `configKey`).
+    - `value`: The new value to set for the configuration.
+    - `updateOverrides`: Any additional overrides for the update.
+    - `target`: Where the configuration update is targeted (e.g., account, organization, etc.).
+
+Once the update is successful, the hook will refetch the configuration data, and the `data` will reflect the updated value.
+
+#### 3. **Skipping Apollo Queries**
+
+In some scenarios, you might want to skip the Apollo query altogether (e.g., if the configuration data is already up-to-date or doesn’t need fetching at that moment). You can use the `skip` parameter in the hook’s input.
+
+```tsx
+const NotificationSettings = () => {
+    const { data } = useSettingsLoader({
+        configKey: 'account.notification.primaryEmail',
+        skip: true,
+    });
+
+    return <div>{data ? `Notification Email: ${data}` : 'No email set'}</div>;
+};
+```
+
+---
+
+### Error Handling
+
+Always ensure you handle the `error` state returned by the hook. Errors could occur due to network issues, GraphQL errors, or even loader issues.
+
+```tsx
+const NotificationSettings = () => {
+    const { data, loading, error } = useSettingsLoader({
+        configKey: 'account.notification.primaryEmail',
+    });
+
+    if (loading) {
+        return <div>Loading settings...</div>;
+    }
+
+    if (error) {
+        return <div>Error loading settings: {error.message}</div>;
+    }
+
+    return <div>{`Notification Email: ${data}`}</div>;
+};
+```
+
+---
+
+### Testing Components Using `useSettingsLoader`
+
+When writing tests for components that use `useSettingsLoader`, you will need to mock both `useLoaderData` (for initial data) and the Apollo Client (for updates or refetches). Additionally, you should wrap your test in a `MemoryRouter` and `ApolloProvider`.
+
+Here’s a basic test setup:
+
+```tsx
+import { render, screen, waitFor, act } from '@testing-library/react';
+import { createRemixStub, json } from '@remix-run/testing'; // Remix testing utilities
+import MyComponent from './MyComponent'; // The component using useSettingsLoader
+import { DefaultConfiguration } from './fixtures/default-configuration';
+
+const preferencesInput = {
+    editableSettingsInput: 'some-input',
+};
+
+describe('useSettingsLoader Hook Test with RemixStub', () => {
+    it('should load initial configuration from loader', async () => {
+        // Create a RemixStub for the test
+        const RemixStub = createRemixStub([
+            {
+                path: '/',
+                Component: MyComponent,
+                loader() {
+                    return json({
+                        configurations: DefaultConfiguration.contents,
+                        dataContext: { preferencesInput: preferencesInput },
+                    });
+                },
+            },
+        ]);
+
+        // Render the component within the RemixStub
+        await act(async () => {
+            render(<RemixStub />);
+        });
+
+        // Wait for the component to load and check the configuration output
+        await waitFor(() => {
+            expect(screen.getByTestId('config-output').textContent).toContain(
+                JSON.stringify(DefaultConfiguration.contents.organization.teams.visibility),
+            );
+        });
+
+        // Simulate updating the configuration
+        const updateButton = screen.getByRole('button', { name: /Update Email/i });
+        await act(async () => {
+            updateButton.click();
+        });
+
+        // Check if the new value is rendered after the update
+        await waitFor(() => {
+            expect(screen.getByTestId('config-output').textContent).toContain('new-email@example.com');
+        });
+    });
+});
+```
+
+---
+
+### Best Practices
+
+1. **Efficient Query Usage**: Use the `skip` option when you don’t need to fetch the configuration data, such as in scenarios where the data is already available or doesn't need to be refetched.
+2. **Optimize for Performance**: Ensure you leverage the `cache-first` policy of Apollo Client to avoid unnecessary network requests. Use the `skip` parameter wisely when refetching is unnecessary.
+
+3. **Error Handling**: Always handle errors gracefully. Whether during the initial fetch or a refetch, providing fallback UI for error states improves the user experience.
+
+---
+
+### Conclusion
+
+The `useSettingsLoader` hook offers an efficient way to manage configuration settings in your React applications, particularly when using Remix and Apollo Client. It handles both initial data loading via `useLoaderData` and updates via Apollo Client’s GraphQL queries. Whether you're fetching configurations initially or updating them, `useSettingsLoader` provides the flexibility and scalability you need to manage configuration settings efficiently in any React environment.