@manufac/sculptor 1.0.0

package/src/guidelines/React.md

@@ -0,0 +1,502 @@
+### React Coding Guidelines
+
+#### Component Structure
+
+1. **Component Naming**
+   - Each component name should be PascalCase.
+
+   ```ts
+   // Correct
+   function UserProfile(): JSX.Element {
+     return <div>Profile</div>;
+   }
+
+   // Incorrect
+   function userProfile(): JSX.Element {
+     return <div>Profile</div>;
+   }
+   ```
+
+2. **Component Declaration**
+   - Each component should be declared using the `function` keyword.
+
+   ```ts
+   // Correct
+   function Button(): JSX.Element {
+     return <button>Click</button>;
+   }
+
+   // Incorrect - arrow function
+   const Button = (): JSX.Element => {
+     return <button>Click</button>;
+   };
+   ```
+
+3. **Return Type**
+   - Each component should have an explicit return type of `JSX.Element`.
+
+   ```ts
+   function UserCard(): JSX.Element {
+     return <div>User Card</div>;
+   }
+   ```
+
+4. **Props Destructuring**
+   - Props should be destructured in the component parameters if less than 3.
+
+   Example:
+
+   ```ts
+   interface UserCardProps {
+     name: string;
+     email: string;
+   }
+
+   // Correct
+   function UserCard({ name, email }: UserCardProps): JSX.Element {
+     return (
+       <div>
+         <Text>{name}</Text>
+         <Text>{email}</Text>
+       </div>
+     );
+   }
+
+   // Incorrect
+   function UserCard(props: UserCardProps): JSX.Element {
+     return (
+       <div>
+         <Text>{props.name}</Text>
+         <Text>{props.email}</Text>
+       </div>
+     );
+   }
+   ```
+
+5. **Unused Props**
+   - Avoid passing props that are not used inside the component.
+
+   ```ts
+   interface ButtonProps {
+     label: string;
+     onClick: MouseEventHandler<HTMLButtonElement>;
+   }
+
+   // Correct - only pass what's needed
+   <Button label="Submit" onClick={handleClick} />
+
+   // Incorrect - passing unused prop
+   <Button label="Submit" onClick={handleClick} unused={someValue} />
+   ```
+
+#### Type Safety
+
+6. **Avoid Wide Types**
+   - Avoid using wide types like `ReactNode` or `ReactElement` unless absolutely necessary.
+   - Only use wide types when the component genuinely accepts any valid React children.
+   - Always add a comment explaining why the wide type is necessary.
+
+   ```ts
+   interface CardProps {
+     // ReactNode is necessary here because this component accepts any valid React children
+     // including strings, numbers, elements, fragments, and portals
+     children: ReactNode;
+     title: string;
+   }
+
+   function Card({ children, title }: CardProps): JSX.Element {
+     return (
+       <div>
+         <Title>{title}</Title>
+         {children}
+       </div>
+     );
+   }
+   ```
+
+7. **Handler Type Safety**
+   - Each `onChange` handler, `onClick` handler, and other event handlers should have appropriately declared types.
+   - Use component-specific prop types or React's event handler types.
+
+   ```ts
+   import type { MouseEventHandler } from 'react';
+   import type { TextInputProps } from '@mantine/core';
+
+   interface FormProps {
+     onSubmit: MouseEventHandler<HTMLButtonElement>;
+     onChange: TextInputProps["onChange"];
+   }
+
+   function Form({ onSubmit, onChange }: FormProps): JSX.Element {
+     return (
+       <form>
+         <TextInput onChange={onChange} />
+         <Button onClick={onSubmit}>Submit</Button>
+       </form>
+     );
+   }
+   ```
+
+#### Code Organization
+
+8. **Handler Functions**
+   - All handlers declared inside the component should be arrow functions.
+
+   ```ts
+   function UserForm(): JSX.Element {
+     // Correct - arrow function
+     const handleSubmit: MouseEventHandler<HTMLButtonElement> = (event) => {
+       event.preventDefault();
+       // Handle submit
+     };
+
+     // Incorrect - function declaration
+     function handleSubmit(event: MouseEvent<HTMLButtonElement>): void {
+       event.preventDefault();
+     }
+
+     return <Button onClick={handleSubmit}>Submit</Button>;
+   }
+   ```
+
+9. **Utility Functions**
+   - Extract business logic, calculations, and data transformations into utility functions.
+   - Move utility functions outside the component into a `utils.ts` file.
+
+   ```ts
+   // utils.ts
+   export function calculateTotal(items: CartItem[]): number {
+     return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+   }
+
+   export function formatCurrency(amount: number): string {
+     return new Intl.NumberFormat('en-US', {
+       style: 'currency',
+       currency: 'USD',
+     }).format(amount);
+   }
+
+   // CartSummary/index.tsx
+   import { calculateTotal, formatCurrency } from './utils';
+
+   function CartSummary({ items }: CartSummaryProps): JSX.Element {
+     const total = calculateTotal(items);
+
+     return <Text>{formatCurrency(total)}</Text>;
+   }
+   ```
+
+10. **File Naming Convention**
+    - All component file names should follow the pattern `ComponentName/index.tsx`.
+    - If a file does not contain any component, its extension should not be `.tsx`.
+
+    ```text
+    src/
+      components/
+        UserProfile/
+          index.tsx        // Component file
+          utils.ts         // Utility functions (no JSX)
+          types.ts         // Type definitions (no JSX)
+          styles.module.css
+        Button/
+          index.tsx
+    ```
+
+#### Data Fetching & Mutations
+
+11. **TanStack Query**
+    - Use TanStack Query for all data fetching and mutations.
+    - Use `useQuery` for fetching data.
+    - Use `useMutation` for creating, updating, or deleting data.
+    - Define query keys in a separate constants file for reusability.
+
+    ```ts
+    // queryKeys.ts
+    export const queryKeys = {
+      users: {
+        all: ['users'] as const,
+        detail: (id: string) => ['users', id] as const,
+      },
+    };
+
+    // useGetUser.ts
+    import { useQuery } from '@tanstack/react-query';
+    import { queryKeys } from './queryKeys';
+
+    interface User {
+      id: string;
+      name: string;
+      email: string;
+    }
+
+    function fetchUser(userId: string): Promise<User> {
+      return fetch(`/api/users/${userId}`).then((res) => res.json());
+    }
+
+    export function useGetUser(userId: string) {
+      return useQuery({
+        queryKey: queryKeys.users.detail(userId),
+        queryFn: () => fetchUser(userId),
+      });
+    }
+
+    // useUpdateUser.ts
+    import { useMutation, useQueryClient } from '@tanstack/react-query';
+    import { queryKeys } from './queryKeys';
+
+    interface UpdateUserParams {
+      userId: string;
+      data: Partial<User>;
+    }
+
+    function updateUser(params: UpdateUserParams): Promise<User> {
+      return fetch(`/api/users/${params.userId}`, {
+        method: 'PATCH',
+        body: JSON.stringify(params.data),
+      }).then((res) => res.json());
+    }
+
+    export function useUpdateUser() {
+      const queryClient = useQueryClient();
+
+      return useMutation({
+        mutationFn: updateUser,
+        onSuccess: (data) => {
+          queryClient.invalidateQueries({
+            queryKey: queryKeys.users.detail(data.id),
+          });
+        },
+      });
+    }
+
+    // UserProfile/index.tsx
+    function UserProfile({ userId }: UserProfileProps): JSX.Element {
+      const { data: user, isPending } = useGetUser(userId);
+      const { mutate: updateUser } = useUpdateUser();
+
+      const handleUpdate: MouseEventHandler<HTMLButtonElement> = () => {
+        updateUser({ userId, data: { name: 'New Name' } });
+      };
+
+      if (isPending) {
+        return <Loader />;
+      }
+
+      return (
+        <div>
+          <Text>{user?.name}</Text>
+          <Button onClick={handleUpdate}>Update</Button>
+        </div>
+      );
+    }
+    ```
+
+#### Modern React Patterns
+
+12. **React 19 Best Practices**
+    - Follow React 19 best practices from https://react.dev/blog/2024/12/05/react-19
+    - Use React 19 Actions for form submissions and mutations when not using TanStack Query.
+    - Prefer the `use` hook for reading promises and context.
+    - Utilize ref callbacks for DOM measurements.
+    - Use `useOptimistic` for optimistic UI updates.
+
+    ```ts
+    // Using Actions for form submission (when not using TanStack Query)
+    import { useActionState } from 'react';
+
+    async function submitForm(prevState: FormState, formData: FormData): Promise<FormState> {
+      const name = formData.get('name') as string;
+      // Process form data
+      return { success: true, message: 'Form submitted' };
+    }
+
+    function ContactForm(): JSX.Element {
+      const [state, formAction, isPending] = useActionState(submitForm, {
+        success: false,
+        message: '',
+      });
+
+      return (
+        <form action={formAction}>
+          <TextInput name="name" />
+          <Button type="submit" loading={isPending}>
+            Submit
+          </Button>
+          {state.message !== '' ? <Text>{state.message}</Text> : null}
+        </form>
+      );
+    }
+    ```
+
+13. **Escape hatches**
+    - Refer https://react.dev/learn/escape-hatches for detecting escape hatches.
+    - Any usage of an escape hatch must include a comment explaining:
+      - Why it is necessary
+      - Why a declarative alternative was not possible
+      - What risk it introduces
+
+#### Performance Optimization
+
+14. **Memoization**
+    - Use `memo` to prevent unnecessary re-renders of components that receive the same props.
+    - Use `useMemo` for expensive calculations.
+    - Use `useCallback` for functions passed as props to memoized components.
+    - Always add comments explaining why memoization is necessary.
+
+    ```ts
+    import { memo, useMemo, useCallback } from 'react';
+
+    interface ExpensiveListProps {
+      items: Item[];
+      onItemClick: (id: string) => void;
+    }
+
+    // Memoized to prevent re-renders when parent re-renders
+    // but items and onItemClick remain the same
+    export const ExpensiveList = memo(function ExpensiveList({
+      items,
+      onItemClick,
+    }: ExpensiveListProps): JSX.Element {
+      // Expensive calculation memoized to avoid recalculation on every render
+      const sortedItems = useMemo(() => {
+        return [...items].sort((a, b) => a.priority - b.priority);
+      }, [items]);
+
+      return (
+        <Stack>
+          {sortedItems.map((item) => (
+            <ItemCard key={item.id} item={item} onClick={onItemClick} />
+          ))}
+        </Stack>
+      );
+    });
+
+    function ItemList(): JSX.Element {
+      const { data: items } = useGetItems();
+
+      // Memoized because it's passed to a memoized component
+      const handleItemClick = useCallback((id: string) => {
+        console.log('Item clicked:', id);
+      }, []);
+
+      return <ExpensiveList items={items ?? []} onItemClick={handleItemClick} />;
+    }
+    ```
+
+15. **List Rendering**
+    - Always provide a unique, stable `key` prop when rendering lists.
+    - Use unique identifiers (IDs) as keys, not array indices.
+    - Add a comment if array index must be used as a key.
+
+    ```ts
+    // Correct - using unique ID
+    function UserList({ users }: UserListProps): JSX.Element {
+      return (
+        <Stack>
+          {users.map((user) => (
+            <UserCard key={user.id} user={user} />
+          ))}
+        </Stack>
+      );
+    }
+
+    // Incorrect - using array index
+    function UserList({ users }: UserListProps): JSX.Element {
+      return (
+        <Stack>
+          {users.map((user, index) => (
+            <UserCard key={index} user={user} />
+          ))}
+        </Stack>
+      );
+    }
+
+    // Acceptable with comment - when items have no unique identifier
+    function StaticList({ items }: StaticListProps): JSX.Element {
+      return (
+        <Stack>
+          {items.map((item, index) => (
+            // Index used as key because items are static and have no unique identifier
+            <Text key={index}>{item}</Text>
+          ))}
+        </Stack>
+      );
+    }
+    ```
+
+#### Conditional Rendering
+
+16. **Conditional Rendering Patterns**
+    - Use explicit `if` statements for complex conditions or when performing side effects.
+    - Use ternary operators for simple conditional rendering.
+    - Use logical `&&` operator only for boolean conditions, never for truthy/falsy checks.
+    - Always ensure the left side of `&&` evaluates to a boolean.
+
+    ```ts
+    function UserProfile({ user }: UserProfileProps): JSX.Element {
+      // Correct - explicit boolean check with &&
+      return (
+        <Stack>
+          {user.isActive === true && <Badge>Active</Badge>}
+
+          {/* Correct - ternary for simple either/or */}
+          {user.isPremium === true ? <PremiumBadge /> : <FreeBadge />}
+        </Stack>
+      );
+    }
+
+    function ProductList({ products }: ProductListProps): JSX.Element {
+      // Incorrect - truthy check with && can render 0
+      // {products.length && <Text>Products available</Text>}
+
+      // Correct - explicit boolean check
+      if (products.length === 0) {
+        return <Text>No products available</Text>;
+      }
+
+      return (
+        <Stack>
+          {products.map((product) => (
+            <ProductCard key={product.id} product={product} />
+          ))}
+        </Stack>
+      );
+    }
+    ```
+
+#### Custom Hooks
+
+17. **Custom Hook Conventions**
+    - Custom hooks must start with `use` prefix.
+    - Extract reusable logic into custom hooks.
+    - Custom hooks should have explicit return types.
+    - Place custom hooks in a `hooks` directory.
+
+    ```ts
+    // hooks/useLocalStorage.ts
+    import { useState, useEffect } from "react";
+
+    interface UseLocalStorageReturn<T> {
+      value: T;
+      setValue: (value: T) => void;
+      removeValue: () => void;
+    }
+
+    export function useLocalStorage<T>(key: string, initialValue: T): UseLocalStorageReturn<T> {
+      const [value, setValue] = useState<T>(() => {
+        const item = window.localStorage.getItem(key);
+        return item !== null ? JSON.parse(item) : initialValue;
+      });
+
+      useEffect(() => {
+        window.localStorage.setItem(key, JSON.stringify(value));
+      }, [key, value]);
+
+      const removeValue = (): void => {
+        window.localStorage.removeItem(key);
+        setValue(initialValue);
+      };
+
+      return { value, setValue, removeValue };
+    }
+    ```

package/src/guidelines/Typescript.md

@@ -0,0 +1,53 @@
+### Coding conventions guidelines
+
+1. All top-level and named functions must be declared using a `function` declaration.
+2. Arrow functions are permitted only for callbacks and inline anonymous functions.
+3. Function expression is not allowed.
+4. All functions must explicitly declare their return type.
+5. If a function has more than 2 parameters, require a single object parameter typed using an explicit interface or type alias.
+6. Do not use short-circuiting operators (`&&`, `||`) **as a substitute for control-flow or side-effect execution** (e.g. conditionally calling functions or executing statements).
+
+- Short-circuiting operators **are allowed** in pure boolean expressions, conditions, return values, and assignments.
+- Use explicit `if` statements or a ternary operator when performing branching logic or side effects.
+
+5. Condition checks must evaluate to boolean values:
+   - For boolean variables, use direct checks (e.g. `if (isValid)`).
+   - For non-boolean expressions, use explicit comparisons (e.g. `array.length === 0`).
+6. Use `array.at(0)` to access the element of an array.
+7. For derived objects, use `as const satisfies`:
+
+```ts
+interface XYZ {
+  name: string;
+  email: string;
+}
+
+const XYZFormNames = {
+  name: "name",
+  email: "email",
+} as const satisfies Record<keyof XYZ, keyof XYZ>;
+
+const XYZFormLabels = {
+  name: "Full Name",
+  email: "Email Address",
+} as const satisfies Record<keyof XYZ, string>;
+```
+
+8. For un-derived objects use type declaration.
+   Example:
+
+```ts
+const User = {
+  name: "abc",
+  email: "xyz",
+}; // This is incorrect
+
+interface User {
+  name: string;
+  email: string;
+}
+const UserDetails: User = {
+  name: "abc",
+  email: "xyz",
+}; // This is correct.
+```

package/src/guidelines/TypescriptNamingConventions.md

@@ -0,0 +1,117 @@
+### Variable naming guidelines
+
+- Identify project domain using project codebase.
+- Use domain-driven development guidelines regarding naming conventions.
+- Abbreviated/acronym in the variable names should be all in uppercase.
+  example:
+  - testURL is preferred instead of testUrl
+  - chartID is preferred instead of chartId
+  - userIDs is preferred instead of userIds
+  - httpURL is preferred instead of httpUrl
+- Check for spelling errors in the variable names.
+- If a compound word exists as a single dictionary word, it should not have camel casing. When uncertain if a compound word is a single dictionary entry, consult standard dictionaries (Merriam-Webster, Oxford)
+  example:
+  - subtitle is correct while subTitle is incorrect
+  - database is correct while dataBase is incorrect
+  - username is correct while userName is incorrect
+- When a compound dictionary word contains an acronym, the acronym rule takes precedence.
+  example:
+  - databaseURL is correct while databaseUrl is incorrect
+- Global variables should be PascalCase except for global variables that are arrow functions or higher order functions, which should be camelCase.
+  example:
+  - `const UserConfig = {...}` (PascalCase for regular global variable)
+  - `const fetchData = () => {...}` (camelCase for global arrow function)
+  - `const withAuth = (component) => {...}` (camelCase for global HOF)
+- Variable names should be in camelCase or PascalCase. No other format is accepted.
+  - Use camelCase for local variables and function parameters
+  - Use PascalCase for classes, components, and global variables but functions names should not use pascal case.
+  - Snake cases or screaming snake case are not accepted. We are intentionally avoiding the snake case naming for constants even though it is preferred by JS conventions.
+    example:
+    - `const MAX_RETRY_COUNT = 5` is incorrect while `const MaxRetryCount = 5` is correct
+    - `const user_id = response.user_id` is incorrect while `const userID = response.user_id` is correct (follows camelCase with uppercase acronym rule)
+  - When mapping API responses with nested objects, transform all levels from snake_case to camelCase.
+    example:
+    - `const user = { userID: response.user_id, profileData: response.profile_data }` is correct
+  - Kebab case values are allowed only in object values.
+    example:
+    - `const styles = { className: "user-profile" }` (kebab-case string value is OK)
+    - `const config = { "user-id": 123 }` (kebab-case as object key is incorrect)
+- Use only named imports and exports.
+- All boolean variables should start with a helping verb: `is`, `has`, `can`, or `should`.
+  example:
+  - isNull, isValid, isLoading
+  - hasPermission, hasError
+  - canEdit, canDelete
+  - shouldUpdate, shouldRender
+- Negative boolean conditions should be avoided unless necessary for code readability. When used, they must be accompanied by a comment explaining the positive context.
+  example:
+  - ❌ `const isInvalid = checkValidation()` (avoid negative naming)
+  - ✅ `const isValid = checkValidation()` (use positive naming with ! operator when needed)
+  - ✅ `const isDisabled = true // Indicates the button cannot be clicked` (acceptable with explanatory comment)
+
+### Types naming conventions
+
+- Interface names should be PascalCase and they should not start with `I`.
+  example:
+  - IUser is invalid while User is valid interface name
+
+  ```ts
+  // ❌ Invalid
+  interface IUser {
+    name: string;
+  }
+
+  // ✅ Valid
+  interface User {
+    name: string;
+  }
+  ```
+
+- Type alias names should be PascalCase.
+  example:
+  - `type UserRole = string | number` (PascalCase type name)
+- Avoid type aliases unless necessary for union types or mapped types. Prefer interfaces for object shapes.
+  example:
+  - `type UserRole = string | number` (acceptable for union types)
+  - `type User = { name: string }` (avoid, use interface instead)
+  - `interface User { name: string }` (preferred)
+- Union types are allowed when used with:
+  - Primitive types
+    - `type UserRole = string | number` (PascalCase type name)
+  - Complex types (interfaces, objects)
+    ```ts
+    interface User {
+      email: string;
+      role: string;
+    }
+    type Actor = string | User;
+    ```
+- Enums should not be used. Use union types with const objects instead.
+  example:
+  - ❌ `enum UserRole { Admin, Editor, Viewer }`
+- Predefined / Finite Domain Values
+  - If a value is predefined and limited (e.g. roles like admin, user, editor):
+  - You must create a const dictionary
+  - The dictionary name must be PascalCase
+  - Use as const
+  - Derive the type using keyof typeof
+
+  ```TS
+      const UserRoles = {
+      Admin: 'admin',
+      Editor: 'editor',
+      Viewer: 'viewer',
+      } as const
+
+      type UserRole = (typeof UserRoles)[keyof typeof UserRoles]
+
+      interface User {
+          email: string
+          role: UserRole
+      }
+  ```
+
+### File naming conventions
+
+1. All `*.ts` file name should be kebab cased.
+2. All `*.md` file name should be Pascal case.