@bunnyapp/components 1.6.0-beta.2 → 1.6.0-beta.21

package/README.md

@@ -30,6 +30,56 @@ Ensure all peer dependencies in the package.json are installed.
 
 To run the development server, run `npm run dev`.
 
+### Folder structure
+
+Unfortunately, the current folder structure isn't perfect. The goal is to progressively (whenever making changes) to begin to follow a module oriented structure.
+
+This folder structure is inspired by [Twenty's frontend development folder architecture](https://docs.twenty.com/developers/frontend-development/folder-architecture-front#ui).
+
+**Structure**
+
+By following this folder architecture convention, it's easier to find the files related to specific features and ensure that the components are scalable and maintainable.
+
+```
+src/
+└───modules
+│   └───module1
+│   │   └───submodule1
+│   └───module2
+│   └───components
+│   │   └───display
+│   │   └───inputs
+│   │   │   └───buttons
+│   │   └───...
+└───...
+```
+
+**Modules**
+
+Each module represents a feature or a group of feature, comprising its specific components, states, and operational logic. They should all follow the structure below. You can nest modules within modules (referred to as submodules) and the same rules will apply.
+
+```
+module1
+├── components/
+│   └───stories/
+│   ├── component1/
+│   └── component2/
+├── constants/
+├── contexts/
+├── graphql/
+│   ├── fragments/
+│   ├── queries/
+│   └── mutations/
+├── hooks/
+├── types/
+└── utils/
+└── ...
+```
+
+**Interface and dependencies**
+
+You can import other module code from any module except for components exported in the index.ts file in the components folder. This will keep its code easy to test and maintain.
+
 ### Using gql.tada for typed queries and mutations
 
 We use [gql.tada](https://gql-tada.0no.co/get-started/) to automatically derive types from GraphQL queries and mutations.
@@ -54,6 +104,69 @@ npm run codegen
 npx gql-tada doctor
 ```
 
+### Development best practices
+
+**Updating the React Query cache with typed data**
+
+Sometimes you want to update the React Query cache directly instead of running another query.  
+To keep this safe, you should make sure the data you write into the cache is **strongly typed** and matches what your components expect.  
+One simple pattern is to create small hooks that accept a GraphQL fragment, and use that fragment to type the data you store in the cache.
+
+Below is a minimal, generic example using a `FruitFragment` and a `useSetFruitQueryData` hook:
+
+```typescript
+const FruitFragment = graphql(`
+  fragment FruitFragment on Fruit {
+    id
+    name
+  }
+`);
+
+export const useSetFruitQueryData = () => {
+  const queryClient = useQueryClient();
+
+  const setFruitQueryData = (
+    fruitId: string,
+    maskedFruit: FragmentOf<typeof FruitFragment> | null
+  ) => {
+    queryClient.setQueryData(['fruit', fruitId], maskedFruit);
+  };
+
+  return { setFruitQueryData };
+};
+```
+
+Using this hook, the data you write to the cache is constrained by the `FragmentOf<typeof FruitFragment>` type:
+
+```typescript
+const { setFruitQueryData } = useSetFruitQueryData();
+
+setFruitQueryData('123', { id: '123', name: 'Apple' });
+```
+
+For a more complete example in the codebase, see the `useSetQuoteQueryData` hook in the `quantityChangeDrawer` module.
+
+### Deprecating @bunnyapp/common
+
+We are gradually deprecating `@bunnyapp/common` and moving types and enums locally to this repository. When something is moved from `@bunnyapp/common`, follow this pattern:
+
+1. **Create local definitions**:
+
+   - **Enums** → Create in `src/enums/` directory (e.g., `src/enums/SubscriptionState.ts`)
+   - **Types** → Create in `src/types/` directory (e.g., `src/types/billingDetails.ts`)
+
+2. **Update imports incrementally**: Only update the files that need the change. Other files can continue importing from `@bunnyapp/common` until they need to be updated.
+
+3. **Example pattern**:
+
+   ```typescript
+   // Before (from @bunnyapp/common)
+   import { SubscriptionState } from '@bunnyapp/common';
+
+   // After (local enum)
+   import SubscriptionState from '../enums/SubscriptionState';
+   ```
+
 ### Storybook stories
 
 To view the storybook stories, run `npx storybook dev`.