@mallardbay/cursor-rules 1.0.14 → 1.0.16

package/.cursor/rules/code-quality.mdc

@@ -0,0 +1,53 @@
+---
+description: Defines structure, naming, reuse, and dependency guidelines to ensure clean, maintainable, and consistent TypeScript code across the project—favoring pragmatism, proven libraries, and shared conventions.
+alwaysApply: false
+---
+
+# Code Quality Standards
+
+## Code Structure
+
+-   Maximum file length: 200 lines
+-   Maximum function length: 50 lines
+-   Naming conventions:
+    -   Components: PascalCase
+    -   Functions: camelCase
+    -   Constants: UPPER_SNAKE_CASE
+    -   Types: PascalCase
+-   Types should be defined at the bottom of files
+-   PropTypes should be defined before component definitions
+-   Prefer using alias for importing components. Only use relative for tests or when there's a direct sibling
+
+## Code Reuse
+
+-   Use shared libraries to avoid duplication
+-   Primary libraries to use:
+    -   [@mallardbay/lib-react-components](mdc:package.json)
+    -   [@mallardbay/lib-shared-helpers](mdc:package.json)
+
+## Third party libraries
+
+-   Favor battle-tested libraries over custom solutions. If a well-maintained, widely-used library solves the problem cleanly, use it. Reinventing functionality that’s already solid, reliable, and well-documented usually leads to more bugs, more maintenance, and wasted time.
+-   Prioritize stability and ecosystem fit. Pick libraries that are actively maintained, have strong adoption, and fit well within our existing tech stack. Avoid fringe or unmaintained packages unless there’s a strong reason.
+-   Suggest existing libraries during code review. If you spot hand-rolled code that could be replaced with a proven library, flag it. Examples:
+-   Use zod or yup instead of custom input validation
+-   Use date-fns instead of writing date math from scratch
+-   Use radash for utility-heavy logic if readability or testability improves
+-   Use react-hook-form for complex form state handling
+-   Be pragmatic. Sometimes a simple custom solution is faster and easier than pulling in a heavy dependency—but always weigh short-term gains against long-term cost.
+-   Make reuse easy. If we do build something custom, design it to be clean, reusable, and well-documented. That way, we’re not creating another wheel, but investing in something worth maintaining.
+
+## String Constants
+
+-   Use constants instead of string literals for:
+    -   Copy text (UI content). Most projects have a `copy-constants` file
+    -   Test IDs. Most projects have `TEST_IDS` defined
+    -   Error messages
+    -   URLs
+-   Source constants from:
+    -   @mallardbay/lib-shared-helpers
+    -   Local constants files
+
+## Cursor Rules
+
+-   Suggest cursor rules as needed

package/.cursor/rules/code-review.mdc

@@ -0,0 +1,46 @@
+---
+description: Outlines expectations for pull request size, test coverage, documentation, and review process—promoting focused, well-tested, and maintainable contributions that align with team standards and improve review efficiency.
+alwaysApply: false
+---
+
+# Code Review Standards
+
+## Pull Request Guidelines
+
+### Size Requirements
+
+-   Maximum PR size: 400 lines
+-   Split large changes into smaller, focused PRs
+-   Keep changes atomic and focused
+-   Consider impact on review process
+
+## Testing Requirements
+
+Ensure comprehensive test coverage:
+
+### Test Coverage
+
+-   All new code must include tests
+-   Follow testing standards in [testing.mdc](mdc:.cursor/rules/testing.mdc)
+-   Include unit tests for new functionality
+-   Avoid making a ton of changes to existing tests while refactoring
+
+### Code Documentation
+
+-   Document complex logic with comments
+-   Explain non-obvious implementation details
+-   Document features added and important caveats in README
+
+### Review Process
+
+-   Review for code quality
+-   Check for test coverage
+-   Verify documentation
+-   Ensure adherence to project standards
+
+## Best Practices
+
+-   Keep PRs focused and manageable
+-   Include clear PR descriptions
+-   Reference related issues/tickets
+-   Respond to review comments promptly

package/.cursor/rules/error-handling.mdc

@@ -0,0 +1,48 @@
+---
+description: Defines consistent patterns for API and form error handling—focusing on clear user feedback, robust validation, and reliable logging to improve user experience, developer debugging, and overall app resilience.
+alwaysApply: false
+---
+
+# Error Handling Standards
+
+## API Error Handling
+
+Implement comprehensive API error handling
+
+### Error Types
+
+-   Handle network errors
+-   Handle server errors
+-   Handle validation errors
+-   Handle Apollo-specific errors
+
+### Error Presentation
+
+-   Show error toasts for user feedback
+-   Use original error messages when appropriate
+-   Provide clear, actionable error messages
+-   Log errors for debugging
+
+## Form Validation
+
+Implement robust form validation
+
+-   Validate all user inputs
+-   Show validation errors clearly
+-   Handle form submission errors
+-   Use [@hookform/resolvers](mdc:package.json) for validation
+
+### Error Display
+
+-   Show validation errors inline
+-   Provide clear error messages
+-   Highlight invalid fields
+-   Prevent form submission with invalid data
+
+## Best Practices
+
+-   Use try-catch blocks appropriately
+-   Implement proper error boundaries
+-   Log errors for debugging
+-   Provide user-friendly error messages
+-   Handle edge cases gracefully

package/.cursor/rules/general-best-practices.mdc

@@ -0,0 +1,163 @@
+---
+description: Core development principles and best practices that always apply—optimized for AI agents to produce clean, maintainable, reviewable code with low cognitive complexity, clear semantics, and incremental changes.
+alwaysApply: true
+---
+
+# General Best Practices
+
+These principles apply to all code changes and should guide every implementation decision.
+
+## Core Principles
+
+### DRY (Don't Repeat Yourself)
+- Extract common logic into reusable functions, utilities, or shared modules
+- Leverage existing patterns and utilities before creating new ones
+- When duplicating code, ask: "Can this be abstracted?"
+- Prefer composition and shared utilities over copy-paste solutions
+
+### Leverage Existing Patterns
+- **Always** search the codebase for similar implementations before creating new code
+- Follow established patterns, conventions, and architectural decisions
+- Use existing utilities, helpers, and shared libraries
+- Match the style and structure of related files
+- When patterns exist, use them consistently—don't invent new approaches without justification
+
+### Incremental Changes
+- **Minimize large changes in a single PR or commit**
+- Break large features into smaller, testable increments
+- Make changes that are easy to review and understand
+- Prefer multiple small PRs over one massive change
+- Each change should be independently testable and reviewable
+- If a change touches many files, consider splitting it into logical phases
+
+### Semantic Clarity
+- Use **semantic, self-documenting names** for functions, variables, and types
+- Function names should clearly describe what they do (e.g., `calculateTotalPrice` not `calc`)
+- Variable names should express intent (e.g., `userAccountBalance` not `bal`)
+- Terminology should be consistent across the codebase
+- Avoid abbreviations unless they're widely understood in the domain
+- Names should make code readable without comments
+
+### Cognitive Complexity
+- **Keep cognitive complexity low**—code should be easy to understand at a glance
+- Prefer early returns and guard clauses over deep nesting
+- Break complex logic into smaller, well-named functions
+- Maximum nesting depth: 3 levels
+- Use intermediate variables to clarify intent
+- Extract complex conditionals into named boolean functions
+- Avoid deeply nested ternaries—use if/else or extract to function
+
+### Separation of Concerns
+- **Files**: Each file should have a single, clear responsibility
+- **Functions**: Each function should do one thing well
+- Separate business logic from presentation, data access, and side effects
+- Keep UI components focused on rendering and user interaction
+- Extract business logic into pure functions or services
+- Avoid god objects or functions that do too much
+
+## Code Quality Standards
+
+### Avoid "AI Slop"
+- **Write code that's easy for humans to review**
+- Avoid generating large amounts of code without understanding context
+- Don't create unnecessary abstractions or over-engineered solutions
+- Remove unused code, imports, and dead branches
+- Clean up commented-out code and debugging statements
+- If an approach doesn't work, **clean up failed attempts** before trying another
+- Keep only relevant, working code—remove experimental code that didn't pan out
+
+### Testing and Linting
+- **Lint and test files related to your changes** before completing work
+- Run linters on modified files and fix issues
+- Run tests for affected modules, not the entire test suite unnecessarily
+- For large changes: **use test sharding**—split tests across multiple runs
+- **Do not run all tests in parallel** when dealing with many changes
+- Tests should be **clear, fast, and minimize setup duplication**
+- Use shared test utilities and fixtures to reduce boilerplate
+- Each test should be independent and runnable in isolation
+
+### Code Organization
+- Group related functionality together
+- Keep related code close (cohesion)
+- Minimize dependencies between modules (loose coupling)
+- Use appropriate data structures for the problem
+- Prefer composition over inheritance
+- Make functions pure when possible (no side effects)
+- Handle edge cases explicitly—don't rely on implicit behavior
+
+### Type Safety and Clarity
+- Use TypeScript types effectively—avoid `any` unless necessary
+- Make types explicit and meaningful
+- Use const assertions and readonly where appropriate
+- Prefer `const` over `let`, avoid `var`
+- Use type guards and discriminated unions for type narrowing
+
+### Performance Considerations
+- Consider performance implications, but **avoid premature optimization**
+- Profile before optimizing—optimize bottlenecks, not everything
+- Use appropriate algorithms and data structures
+- Avoid unnecessary re-renders, re-computations, or API calls
+- Cache expensive computations when appropriate
+
+## AI Agent Workflow
+
+### Before Making Changes
+1. **Create a plan** before making changes directly—outline the approach, identify affected files, and break down the work into steps
+2. **Read existing code** to understand patterns and context
+3. **Search the codebase** for similar implementations
+4. **Check git history** to understand why code exists as it does
+5. **Identify related files** that might be affected
+6. **Ask clarifying questions** if requirements are unclear
+
+### During Implementation
+1. Make **small, incremental changes**
+2. **Test as you go**—verify each change works before moving on
+3. **Lint frequently**—don't accumulate lint errors
+4. **Follow existing patterns**—don't reinvent the wheel
+5. **Use semantic names**—code should be self-documenting
+6. **Keep functions focused**—one responsibility per function
+7. **Extract common logic**—don't duplicate code
+
+### After Making Changes
+1. **Clean up failed attempts**—remove experimental code
+2. **Remove unused code**—imports, variables, functions
+3. **Run linters** on modified files
+4. **Run relevant tests**—not the entire suite unless necessary
+5. **Verify the change works** end-to-end
+6. **Check for side effects**—ensure changes don't break unrelated code
+
+### When Changes Are Large
+1. **Consider splitting** into multiple smaller PRs
+2. **Use test sharding**—run tests in batches, not all at once
+3. **Review incrementally**—make sure each part works before moving on
+4. **Document the approach**—explain why changes are structured this way
+5. **Check impact** on related systems and files
+
+## Anti-Patterns to Avoid
+
+- ❌ Copy-pasting code instead of extracting to a function
+- ❌ Creating new patterns when existing ones work
+- ❌ Making massive changes in one go
+- ❌ Using vague names like `data`, `temp`, `value`, `thing`
+- ❌ Deeply nested conditionals and loops
+- ❌ Functions that do multiple unrelated things
+- ❌ Leaving commented-out code or debugging statements
+- ❌ Skipping tests or linting "to save time"
+- ❌ Running entire test suite for small changes
+- ❌ Leaving experimental code after failed attempts
+- ❌ Premature optimization without profiling
+- ❌ Using `any` types to avoid type errors
+- ❌ Magic numbers or strings without constants
+
+## Remember
+
+**Code is read far more often than it's written.** Write code that:
+- Is easy to understand
+- Is easy to review
+- Is easy to test
+- Is easy to modify
+- Follows established patterns
+- Has clear semantics
+- Minimizes cognitive load
+
+When in doubt, prefer clarity and simplicity over cleverness.

package/.cursor/rules/mallardbay.mdc

@@ -0,0 +1,23 @@
+---
+description: Describes Mallard Bay’s mission to simplify and scale outfitter operations through purpose-built software—emphasizing real-world impact, outfitter collaboration, and a long-term vision to digitize and unify the outdoor experience industry.
+globs:
+alwaysApply: true
+---
+
+# Mallard Bay: Outfitter Management System Overview
+
+Mallard Bay is a specialized platform designed to streamline operations for outfitters—businesses that offer guided outdoor experiences such as hunting, fishing, and eco-tourism. At its core, Mallard Bay operates as an outfitter management system, purpose-built to reduce administrative burden, improve customer experience, and unlock new revenue channels for guides and lodge operators.
+
+# Built for Outfitters, with Outfitters in Mind
+
+At Mallard Bay, we’re not just building software — we’re solving real problems for real people in the outfitting industry. Every feature we ship is grounded in one simple principle: if it doesn’t make an outfitter’s life easier or their business better, it doesn’t belong in our product.
+
+We work closely with outfitters of all sizes to understand their workflows, pain points, and growth challenges. From there, we prioritize meaningful features that drive efficiency, boost bookings, and enhance the guest experience.
+
+Whether it’s reducing no-shows with smart reminders, saving time through automated group booking tools, or enabling instant rebooking with dynamic availability, we’re laser-focused on delivering value — not fluff.
+
+We’re building tools that fit into the way outfitters actually work — not the way a generic booking platform thinks they should.
+
+# Vision
+
+Mallard Bay aims to be the digital backbone for the outfitting industry—a single source of truth for trip logistics, customer interaction, and business growth. The long-term goal is to transform an analog, fragmented market into a digital-first, scalable ecosystem.

package/.cursor/rules/performance.mdc

@@ -0,0 +1,45 @@
+---
+description: Defines best practices for optimizing React components, rendering efficiency, and dependency management—focusing on minimizing re-renders, reducing bundle size, and enabling smooth user experiences through memoization, lazy loading, and performance-aware development.
+alwaysApply: false
+---
+
+# Performance Standards
+
+## React Optimization
+
+Optimize React components for better performance:
+
+### Component Optimization
+
+-   Use `React.memo` for pure components
+-   Implement `useCallback` for function props
+-   Use `useMemo` for expensive computations
+-   Avoid inline function definitions in render
+
+## Rendering Optimization
+
+Prevent unnecessary re-renders:
+
+-   Avoid inline styles in components
+-   Prevent inline object creation in render
+-   Use proper key props in lists
+-   Memoize complex objects and callbacks
+
+### Dependencies
+
+-   Prefer existing dependencies over new ones
+-   Review [package.json](mdc:package.json) before adding new packages
+-   Consider bundle size impact of new dependencies
+-   Use tree-shaking friendly imports
+
+## Best Practices
+
+-   Implement proper code splitting
+-   Use lazy loading for routes and large components
+-   Optimize images and assets
+-   Monitor performance metrics
+-   Use React DevTools for performance profiling
+
+## File Patterns
+
+These rules apply to all TypeScript and TSX files in the project.

package/.cursor/rules/testing.mdc

@@ -0,0 +1,71 @@
+---
+description: Outlines practical, value-driven testing guidelines focused on reliability, developer confidence, and speed. Emphasizes high-impact coverage (not overkill), structured test organization, clear scenarios, and reusable mock/test utilities—enabling fast iteration without sacrificing quality.
+globs:
+alwaysApply: true
+---
+
+# Testing Standards
+
+## Test Coverage and Structure
+
+We aim for high-impact test coverage, focused on adding value and improving developer confidence and experience. The priority is to cover critical logic, edge cases, and integration points where bugs would hurt the most. Tests should act as a safety net and enable fast, fearless iteration—not as a box-ticking exercise.
+
+We do not chase 100% coverage for its own sake. If a test doesn’t meaningfully reduce risk or help developers move faster, it’s not worth writing. The goal is smart coverage, not maximum coverage—optimize for reliability, clarity, and development speed without overengineering.
+
+Avoid e2e tests for UI. Favor unit tests.
+
+### Coverage Requirements
+
+-   Minimum test coverage: 80%
+-   Place tests in `_tests_` directory closest to the file being tested
+-   Use `.spec.ts` or `.spec.tsx` file extensions
+-   Do NOT Use `.test.ts` or `.test.tsx` file extensions
+
+### Test Organization
+
+-   Maximum nesting level: 2
+-   Use `test` or `it` for test cases
+-   Keep tests focused and atomic
+-   Follow AAA pattern (Arrange, Act, Assert)
+
+### Required Scenarios
+
+-   Happy path testing
+-   Error case handling
+-   Edge case coverage within reason. Optimize for branching logic, and avoid creating nearly identical tests
+-   Aim for simplicity
+-   All tests must pass before completion
+
+### Test Quality
+
+-   Write clear, descriptive test names
+-   Test one concept per test case
+-   Avoid test interdependence
+-   Use meaningful assertions
+-   Avoid tests that will make the overall run slower
+
+### Component Testing
+
+-   Use `renderWithProviders` for component tests
+-   Use `renderHookWithProviders` for hook tests
+-   Avoid mocking dependent components
+-   Test component behavior, not implementation
+
+### Mocking Guidelines
+
+-   Use mock helpers instead of inline mocks
+-   Follow existing patterns for:
+    -   Entity mocks
+    -   Apollo mocks
+    -   Provider mocks
+-   Keep mocks simple and maintainable
+
+### Test Utilities
+
+-   Leverage testing utilities from [@testing-library/react](mdc:package.json)
+-   Use [@testing-library/jest-dom](mdc:package.json) for DOM assertions
+-   Follow established patterns in existing tests
+
+## File Patterns
+
+These rules apply to all test files with `.spec.ts` or `.spec.tsx` extensions.

package/.cursor/rules/typescript.mdc

@@ -0,0 +1,27 @@
+---
+alwaysApply: true
+---
+
+# TypeScript Development Standards
+
+## Type Safety
+
+Enforce comprehensive type safety across the codebase:
+
+### Strict Type Checking
+
+Be as strictly as possible where it delivers clear value—specifically in preventing bugs and improving the developer experience. The goal is to enforce strong types and catch issues early, without introducing excessive friction or overhead. If a strict setting improves safety, maintainability, or clarity, we’ll use it. If it creates noise or slows down iteration without real benefit, we’ll dial it back. This is about pragmatic strictness, not dogmatism.
+
+### File Organization
+
+-   Place types at the bottom of files
+-   Define PropTypes before component definitions
+
+## Best Practices
+
+-   Use TypeScript for all new code
+-   Leverage TypeScript's type system for better code quality
+-   Follow React best practices with TypeScript
+-   Use proper type definitions for props and state
+-   Utilize TypeScript's utility types when appropriate
+-   Suggest existing libaries as needed

package/.cursor/rules/ui.mdc

@@ -0,0 +1,91 @@
+---
+description: Defines best practices for building consistent, maintainable, and responsive UI in Mallard Bay projects
+globs:
+alwaysApply: true
+---
+
+# UI Development Standards
+
+## Theme Usage
+
+Use theme values consistently across all components:
+
+### Colors
+
+-   Use theme colors instead of hardcoded values
+-   Example: `theme.colors.primary` instead of `'#000000'`
+
+### Spacing
+
+-   Use theme spacing values for margins and padding
+-   Example: `theme.space[4]` instead of `'16px'`
+
+### Typography
+
+-   Use theme typography settings for text styles
+-   Example: `theme.fontSizes.md` instead of `'16px'`
+
+### Borders and border radius
+
+-   Use theme border styles and radius values
+-   Examples: `theme.borders.sm` instead of `'1px solid'`, `theme.radii.md` instead of using px values
+
+## Component Structure
+
+Maintain clean and consistent component structure:
+
+### Nesting
+
+-   Limit component nesting to maximum depth of 3
+-   Keep component hierarchy readable and maintainable
+
+### Inline Styles
+
+-   Limit inline styles to maximum of 2 per component
+-   Prefer theme-based styling
+
+### Component Library
+
+-   Use existing components in @mallardbay/lib-react-components, @mallardbay/lib-react-components is based off Crakra UI v2
+-   If no component available in @mallardbay/lib-react-components, create one using Crakra UI and place it under src/components/shared/todo-lib-react-components/ to me moved later
+
+## Responsive Design
+
+Ensure responsive and accessible design:
+
+### Breakpoints
+
+-   Use theme breakpoints for responsive design
+-   Implement mobile-first approach
+
+### Spacing
+
+-   Use responsive spacing values
+-   Adapt layouts for different screen sizes
+
+### Animations
+
+-   Use theme transition values for animations
+-   Keep animations smooth and performant
+
+### Rendering
+
+-   Optimize component rendering
+-   Avoid unnecessary re-renders
+-   Use React.memo and useMemo when appropriate
+-   Avoid defining functions inside components to prevent recreation on each render
+-   Move function definitions outside components or use useCallback for event handlers
+-   Use useCallback for functions passed as props to child components
+-   Use useMemo for expensive computations and complex data transformations
+-   Memoize filtered, sorted, or mapped arrays to avoid recalculation on every render
+-   Use useMemo for object/array creation that would otherwise be recreated on each render
+
+## File Patterns
+
+These rules apply to all TypeScript and TSX files in the project.
+
+## Components
+
+-   Keep components small and focused on a single responsibility
+-   Use functional components with hooks instead of class components
+-   Prefer `export default function ImpersonationBox() {` over `function ImpersonationBox(): React.ReactElement | null {` when defining components

package/.cursor/shared/rules/code-quality.mdc

@@ -17,8 +17,6 @@ alwaysApply: false
 -   Types should be defined at the bottom of files
 -   PropTypes should be defined before component definitions
 -   Prefer using alias for importing components. Only use relative for tests or when there's a direct sibling
--   Exported functions should be at the top of the file, with helpers organized by knowledge domain under.
--   React component prop types should be above the component definition.
 
 ## Code Reuse