Added project pages and cards, most of the screens in chris samuels figma design document. Still need to implement project initialization modal and walkthrough, connect to backend and connect to wallet (maybe be beyond scope of this project)
This commit is contained in:
@@ -0,0 +1,525 @@
|
||||
# Component Documentation Standards
|
||||
|
||||
This document outlines the documentation standards for components across the entire project.
|
||||
Following these standards ensures consistency and makes the codebase more maintainable.
|
||||
|
||||
## TypeScript Documentation Approach
|
||||
|
||||
This project uses a **TypeScript-first** documentation approach, focusing on TypeScript's native
|
||||
documentation capabilities rather than traditional JSDoc. While TypeScript supports JSDoc syntax, we
|
||||
prioritize TypeScript-specific documentation patterns where possible.
|
||||
|
||||
### TSDoc vs JSDoc
|
||||
|
||||
- **TSDoc** is a documentation standard specifically designed for TypeScript
|
||||
- We prefer TypeScript's native type annotations over JSDoc type annotations
|
||||
- Use explicit type definitions in code instead of JSDoc type comments when possible
|
||||
- When JSDoc-style comments are needed, use TypeScript-compatible JSDoc tags
|
||||
|
||||
### Documentation Tools
|
||||
|
||||
Our documentation approach is designed to work well with:
|
||||
|
||||
- TypeScript's built-in type checking
|
||||
- IDE integrations like VS Code's IntelliSense
|
||||
- Documentation generators that support TypeScript
|
||||
|
||||
## TypeScript-Specific Documentation Tags
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* This function demonstrates TypeScript-native documentation
|
||||
*
|
||||
* @remarks
|
||||
* The remarks section provides additional details that wouldn't fit in the brief description.
|
||||
*
|
||||
* @typeParam T - Generic type parameter for the input array
|
||||
* @typeParam U - Generic type parameter for the output array
|
||||
*
|
||||
* @param items - Array of items to process (TypeScript infers the type)
|
||||
* @param mapper - Function to transform items (TypeScript infers the signature)
|
||||
* @returns Array of transformed items
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Transform numbers to strings
|
||||
* const numbers = [1, 2, 3];
|
||||
* const strings = mapItems(numbers, n => n.toString());
|
||||
* ```
|
||||
*/
|
||||
function mapItems<T, U>(items: T[], mapper: (item: T) => U): U[] {
|
||||
return items.map(mapper);
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface for configuration options
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface ConfigOptions {
|
||||
/**
|
||||
* Base URL for API requests
|
||||
*/
|
||||
apiUrl: string;
|
||||
|
||||
/**
|
||||
* Authentication token
|
||||
* @defaultValue undefined
|
||||
*/
|
||||
token?: string;
|
||||
|
||||
/**
|
||||
* Request timeout in milliseconds
|
||||
* @defaultValue 3000
|
||||
*/
|
||||
timeout: number;
|
||||
}
|
||||
````
|
||||
|
||||
## Component JSDoc Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* @component ComponentName
|
||||
* @description Brief description of what the component does
|
||||
*
|
||||
* @see [Optional] Link to design reference (e.g., Figma)
|
||||
*
|
||||
* [Optional: Additional context about the component's role in the application]
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <ComponentName prop1="value" prop2={value} />
|
||||
* ```
|
||||
*
|
||||
* @dependencies
|
||||
* - DependencyComponent1
|
||||
* - DependencyComponent2
|
||||
*/
|
||||
````
|
||||
|
||||
## Props Interface Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Props for the ComponentName component
|
||||
* @interface ComponentNameProps
|
||||
* @property {Type} propName - Description of the prop
|
||||
* @property {Type} [optionalProp] - Description of the optional prop
|
||||
* @property {() => void} [onEvent] - Callback fired when event occurs
|
||||
*/
|
||||
interface ComponentNameProps {
|
||||
propName: Type;
|
||||
optionalProp?: Type;
|
||||
onEvent?: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
## Function Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of what the function does
|
||||
* @function functionName
|
||||
* @param {ParamType} paramName - Description of the parameter
|
||||
* @returns {ReturnType} Description of the return value
|
||||
* @throws {ErrorType} Description of potential errors
|
||||
*/
|
||||
function functionName(paramName: ParamType): ReturnType {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Type/Interface Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of what this type/interface represents
|
||||
* @interface InterfaceName
|
||||
* @property {Type} propertyName - Description of the property
|
||||
* @property {Type} [optionalProperty] - Description of the optional property
|
||||
*/
|
||||
interface InterfaceName {
|
||||
propertyName: Type;
|
||||
optionalProperty?: Type;
|
||||
}
|
||||
|
||||
/**
|
||||
* Description of this type alias
|
||||
* @type TypeName
|
||||
*/
|
||||
export type TypeName = BaseType & {
|
||||
additionalProperty: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* Type for use with generic components
|
||||
* @template T - Description of the generic parameter
|
||||
*/
|
||||
export type GenericType<T> = {
|
||||
value: T;
|
||||
label: string;
|
||||
};
|
||||
```
|
||||
|
||||
## Enum Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of what this enum represents
|
||||
* @enum {string|number} EnumName
|
||||
*/
|
||||
export enum EnumName {
|
||||
/**
|
||||
* Description of this enum value
|
||||
*/
|
||||
VALUE_ONE = 'value_one',
|
||||
|
||||
/**
|
||||
* Description of this enum value
|
||||
*/
|
||||
VALUE_TWO = 'value_two',
|
||||
}
|
||||
```
|
||||
|
||||
## Const Assertion Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of this constant object
|
||||
* @const objectName
|
||||
*/
|
||||
export const objectName = {
|
||||
PROPERTY_ONE: 'value_one',
|
||||
PROPERTY_TWO: 'value_two',
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Type derived from const assertion
|
||||
* @type TypeFromConst
|
||||
*/
|
||||
export type TypeFromConst = (typeof objectName)[keyof typeof objectName];
|
||||
```
|
||||
|
||||
## Import/Export Type Guidelines
|
||||
|
||||
When working with TypeScript, use explicit type imports/exports for better clarity:
|
||||
|
||||
```tsx
|
||||
// Preferred: Explicit type imports
|
||||
import type { SomeType, AnotherInterface } from './types';
|
||||
import { Component } from './components';
|
||||
|
||||
// Preferred: Explicit type exports
|
||||
export type { ComponentProps } from './Component';
|
||||
export { Component } from './Component';
|
||||
|
||||
// For re-exporting both the type and value:
|
||||
export { default as Component, type ComponentProps } from './Component';
|
||||
```
|
||||
|
||||
## Barrel File (index.ts) Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* @module ModuleName
|
||||
* @description Brief description of the module's purpose
|
||||
*
|
||||
* This barrel file exports all public components, hooks, and types from the module.
|
||||
* When importing from this module, use the following pattern:
|
||||
* ```tsx
|
||||
* import { ComponentA, ComponentB, useFeature } from '@/path/to/module';
|
||||
* ```
|
||||
*/
|
||||
|
||||
// Component exports
|
||||
export { ComponentA } from './ComponentA';
|
||||
export { ComponentB } from './ComponentB';
|
||||
|
||||
// Hook exports
|
||||
export { useFeatureA } from './hooks/useFeatureA';
|
||||
export { useFeatureB } from './hooks/useFeatureB';
|
||||
|
||||
// Type exports - use explicit type exports
|
||||
export type { ComponentAProps } from './ComponentA';
|
||||
export type { ComponentBProps } from './ComponentB';
|
||||
|
||||
// Enum exports
|
||||
export { FeatureEnum } from './types';
|
||||
|
||||
// Re-export all from a sub-module (use sparingly)
|
||||
export * from './submodule';
|
||||
````
|
||||
|
||||
## Component with Subcomponents Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* Parent component description
|
||||
* @component ParentComponent
|
||||
* @description Overview of the parent component
|
||||
*
|
||||
* @see [Optional] Link to design reference
|
||||
*
|
||||
* Component Hierarchy:
|
||||
* - ParentComponent
|
||||
* - SubComponent1
|
||||
* - SubComponent2
|
||||
* - NestedComponent
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <ParentComponent prop1="value" prop2={value} />
|
||||
* ```
|
||||
*/
|
||||
export function ParentComponent({ prop1, prop2 }: ParentComponentProps) {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
/**
|
||||
* Subcomponent description
|
||||
* @component SubComponent
|
||||
* @description Overview of the subcomponent
|
||||
* @private Only used within ParentComponent
|
||||
*/
|
||||
function SubComponent({ subProp }: SubComponentProps) {
|
||||
// Implementation
|
||||
}
|
||||
````
|
||||
|
||||
## Hooks Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* Description of what the hook does and when to use it
|
||||
* @hook useHookName
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* const { value, setValue } = useHookName(initialValue)
|
||||
* ```
|
||||
*
|
||||
* @param {ParamType} initialValue - Description of the parameter
|
||||
* @returns {ReturnType} Description of the return value
|
||||
*/
|
||||
function useHookName(initialValue: ParamType): ReturnType {
|
||||
// Implementation
|
||||
}
|
||||
````
|
||||
|
||||
## Store Documentation Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* Description of what the store manages
|
||||
* @store storeName
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* const { value, setValue } = useStore()
|
||||
* ```
|
||||
*
|
||||
* State Management:
|
||||
* - value: Description of state value
|
||||
* - setValue: Description of state updater
|
||||
*/
|
||||
````
|
||||
|
||||
## Additional Guidelines
|
||||
|
||||
1. **Be concise but complete** - Provide enough information to understand the component without
|
||||
overwhelming the reader
|
||||
2. **Document public API** - Focus on documenting the public API rather than implementation details
|
||||
3. **Keep examples simple** - Examples should demonstrate common use cases
|
||||
4. **Update documentation** - Keep documentation in sync with code changes
|
||||
5. **Document side effects** - Clearly document any side effects or behaviors that might not be
|
||||
obvious
|
||||
|
||||
## When to Document
|
||||
|
||||
- All components, hooks, and utilities exported from a package or module
|
||||
- Complex internal functions that are difficult to understand at a glance
|
||||
- Props, especially those with non-obvious behavior
|
||||
- State management code and side effects
|
||||
|
||||
## TypeScript-Specific JSDoc Tags
|
||||
|
||||
TypeScript supports JSDoc with additional TypeScript-specific tags. Use these tags to enhance your
|
||||
documentation:
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* @typeParam T - Type parameter description (preferred over @template)
|
||||
* @param param - Parameter with TypeScript type inference (no need for {type})
|
||||
* @returns Return value with TypeScript type inference
|
||||
* @defaultValue Default value for a property
|
||||
* @public Indicates this is part of the public API
|
||||
* @private Indicates this is a private member
|
||||
* @protected Indicates this is a protected member
|
||||
* @readonly Indicates this is a readonly property
|
||||
* @deprecated Indicates this is deprecated with optional explanation
|
||||
*/
|
||||
|
||||
// Property documentation in interfaces/classes
|
||||
interface Example {
|
||||
/**
|
||||
* Property description
|
||||
* @defaultValue 'default'
|
||||
*/
|
||||
property: string;
|
||||
}
|
||||
|
||||
// Documentation for React component props using type alias
|
||||
type ButtonProps = {
|
||||
/**
|
||||
* The button's variant style
|
||||
* @defaultValue 'primary'
|
||||
*/
|
||||
variant?: 'primary' | 'secondary' | 'tertiary';
|
||||
|
||||
/**
|
||||
* Content to display inside the button
|
||||
*/
|
||||
children: React.ReactNode;
|
||||
|
||||
/**
|
||||
* Called when the button is clicked
|
||||
*/
|
||||
onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
|
||||
};
|
||||
|
||||
/**
|
||||
* Function documentation using modern TypeScript patterns
|
||||
*
|
||||
* @deprecated Use newFunction instead
|
||||
* @throws Error when input is invalid
|
||||
*/
|
||||
function oldFunction(input: string): void {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Mermaid Diagrams
|
||||
|
||||
Use Mermaid diagrams to visualize complex relationships, flows, or processes. Include Mermaid
|
||||
diagrams directly in markdown documentation using the following formats:
|
||||
|
||||
### Component Relationship Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @component ComplexFeature
|
||||
- @description A complex feature with multiple components
|
||||
-
|
||||
- ## Component Relationships
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- graph TD
|
||||
- A[ParentComponent] --> B[ChildComponent1]
|
||||
- A --> C[ChildComponent2]
|
||||
- B --> D[GrandchildComponent1]
|
||||
- B --> E[GrandchildComponent2]
|
||||
- C --> F[GrandchildComponent3]
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### Data Flow Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @module DataFlow
|
||||
- @description Shows how data flows through the application
|
||||
-
|
||||
- ## Data Flow
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- graph LR
|
||||
- API[API] --> Store[Store]
|
||||
- Store --> ComponentA[Component A]
|
||||
- Store --> ComponentB[Component B]
|
||||
- ComponentA --> User[User Interface]
|
||||
- ComponentB --> User
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### State Machine Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @component StatefulComponent
|
||||
- @description Component with complex state transitions
|
||||
-
|
||||
- ## State Machine
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- stateDiagram-v2
|
||||
- [*] --> Idle
|
||||
- Idle --> Loading: fetch()
|
||||
- Loading --> Success: data received
|
||||
- Loading --> Error: error thrown
|
||||
- Error --> Loading: retry()
|
||||
- Success --> Idle: reset()
|
||||
- Error --> Idle: reset()
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @function authenticateUser
|
||||
- @description Authentication process flow
|
||||
-
|
||||
- ## Authentication Sequence
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- sequenceDiagram
|
||||
- participant User
|
||||
- participant Client
|
||||
- participant API
|
||||
- participant Database
|
||||
-
|
||||
- User->>Client: Enter credentials
|
||||
- Client->>API: POST /auth/login
|
||||
- API->>Database: Validate credentials
|
||||
- Database-->>API: Valid user
|
||||
- API-->>Client: JWT token
|
||||
- Client-->>User: Login success
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### When to Use Mermaid Diagrams
|
||||
|
||||
- Component hierarchy diagrams for complex nested components
|
||||
- Data flow diagrams for state management patterns
|
||||
- Process flows for complex business logic
|
||||
- State machines for components with multiple states
|
||||
- Sequence diagrams for asynchronous operations
|
||||
|
||||
### Mermaid Diagram Guidelines
|
||||
|
||||
1. Keep diagrams simple and focused on one aspect of the system
|
||||
2. Use consistent naming conventions in diagrams
|
||||
3. Add concise labels to explain relationships
|
||||
4. Include a brief text description above each diagram
|
||||
5. For complex diagrams, consider breaking them into multiple smaller diagrams
|
||||
@@ -0,0 +1,232 @@
|
||||
# Feature Building Process
|
||||
|
||||
This document outlines our standardized approach to building new features. Following this process
|
||||
ensures that features are well-designed, properly structured, thoroughly documented, and
|
||||
consistently implemented.
|
||||
|
||||
## 1. Design and Data Flow Analysis
|
||||
|
||||
Before writing any code, thoroughly analyze the design and data flow requirements:
|
||||
|
||||
### Design Analysis
|
||||
|
||||
- Study the Figma/design mockups thoroughly
|
||||
- Identify all UI components and their states
|
||||
- Note interactions, animations, and transitions
|
||||
- Identify responsive behavior requirements
|
||||
- Document accessibility considerations
|
||||
|
||||
### Data Flow Analysis
|
||||
|
||||
- Map out the data requirements for the feature
|
||||
- Identify data sources and sinks
|
||||
- Document API endpoints that will be used
|
||||
- Define state management needs
|
||||
- Identify where data transformations occur
|
||||
- Document any caching or persistence requirements
|
||||
|
||||
### Output
|
||||
|
||||
Create a Design & Data Requirements document containing:
|
||||
|
||||
- Screenshots/references to relevant design mockups
|
||||
- Component breakdown with states and props
|
||||
- Data flow diagram
|
||||
- API contract expectations
|
||||
- State management approach
|
||||
|
||||
## 2. Structure Planning
|
||||
|
||||
Once the design and data requirements are understood, plan the structure:
|
||||
|
||||
### Routing
|
||||
|
||||
- Define all routes needed for the feature
|
||||
- Document route parameters and query parameters
|
||||
- Specify layout components for each route
|
||||
- Define route guards or access control
|
||||
|
||||
### Component Hierarchy
|
||||
|
||||
- Create a component tree showing parent-child relationships
|
||||
- Identify reusable components vs. feature-specific components
|
||||
- Define prop interfaces for all components
|
||||
- Document component responsibilities and boundaries
|
||||
|
||||
### File Structure
|
||||
|
||||
- Plan the directory structure following project conventions
|
||||
- Define file naming following established patterns
|
||||
- Identify shared utilities, hooks, or helpers needed
|
||||
- Plan test file organization
|
||||
|
||||
### Output
|
||||
|
||||
Create a Structure Plan document containing:
|
||||
|
||||
- Route definitions
|
||||
- Component hierarchy diagram
|
||||
- Directory and file structure plan
|
||||
- List of new files to create with their purpose
|
||||
|
||||
## 3. File Creation with Documentation
|
||||
|
||||
Create skeleton files with comprehensive documentation:
|
||||
|
||||
### For Each Component:
|
||||
|
||||
- Purpose and responsibility
|
||||
- Props interface with detailed documentation
|
||||
- State management approach
|
||||
- Side effects and cleanup
|
||||
- Error handling approach
|
||||
- Expected behaviors for all edge cases
|
||||
- Performance considerations
|
||||
- Testing strategy
|
||||
|
||||
### For Data/API Files:
|
||||
|
||||
- Type definitions
|
||||
- Function signatures with parameters and return types
|
||||
- Error handling approach
|
||||
- Caching strategy
|
||||
- Retry logic
|
||||
|
||||
### For Hooks/Utilities:
|
||||
|
||||
- Purpose and usage examples
|
||||
- Parameters and return values
|
||||
- Side effects
|
||||
- Error scenarios
|
||||
- Performance characteristics
|
||||
|
||||
### Output
|
||||
|
||||
A set of skeleton files with detailed JSDoc comments outlining implementation requirements for each
|
||||
file.
|
||||
|
||||
## 4. Implementation Guide
|
||||
|
||||
Create a comprehensive guide for engineers or AI agents to follow:
|
||||
|
||||
### Implementation Order
|
||||
|
||||
- Dependency graph showing which files should be implemented first
|
||||
- Recommended implementation sequence
|
||||
|
||||
### Critical Requirements
|
||||
|
||||
- Performance requirements
|
||||
- Accessibility requirements
|
||||
- Browser/device compatibility requirements
|
||||
- Error handling expectations
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
- Unit test coverage expectations
|
||||
- Integration test scenarios
|
||||
- E2E test scenarios
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
- Anti-patterns to avoid
|
||||
- Performance pitfalls
|
||||
- Security concerns
|
||||
- Common mistakes
|
||||
|
||||
### Review Checklist
|
||||
|
||||
- Code quality checks
|
||||
- Performance review points
|
||||
- Accessibility review points
|
||||
- Security review points
|
||||
|
||||
## Example: Feature Building for a User Profile Page
|
||||
|
||||
### 1. Design & Data Analysis
|
||||
|
||||
```
|
||||
Design Requirements:
|
||||
- Profile page with user avatar, name, email, and bio
|
||||
- Edit profile form with validation
|
||||
- Activity feed showing recent actions
|
||||
...
|
||||
|
||||
Data Requirements:
|
||||
- User profile data from GET /api/users/:id
|
||||
- Profile updates via PUT /api/users/:id
|
||||
- Activity data from GET /api/users/:id/activity
|
||||
...
|
||||
```
|
||||
|
||||
### 2. Structure Plan
|
||||
|
||||
```
|
||||
Routes:
|
||||
- /profile - Main profile view
|
||||
- /profile/edit - Edit profile form
|
||||
|
||||
Components:
|
||||
- ProfilePage
|
||||
- ProfileHeader
|
||||
- ActivityFeed
|
||||
- ActivityItem
|
||||
- ProfileEditForm
|
||||
- ImageUploader
|
||||
- FormFields
|
||||
...
|
||||
```
|
||||
|
||||
### 3. File Skeleton (Example for ProfileHeader.tsx)
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* @component ProfileHeader
|
||||
* @description Displays the user's profile header with avatar, name, and key information
|
||||
*
|
||||
* Requirements:
|
||||
* - Display user avatar with fallback for missing images
|
||||
* - Show user name, handle, and join date
|
||||
* - Display edit button only if user is viewing their own profile
|
||||
* - Show verified badge if account is verified
|
||||
* - Handle loading and error states
|
||||
* ...
|
||||
*/
|
||||
```
|
||||
|
||||
### 4. Implementation Guide (Excerpt)
|
||||
|
||||
```
|
||||
Implementation Order:
|
||||
1. Types and API functions
|
||||
2. Hooks for data fetching
|
||||
3. Base components (ProfileHeader, ActivityItem)
|
||||
4. Container components (ProfilePage, ActivityFeed)
|
||||
5. Form components
|
||||
|
||||
Do NOT:
|
||||
- Make direct API calls from components - use the defined hooks
|
||||
- Store sensitive user data in localStorage
|
||||
- Use inline styles except for dynamically calculated values
|
||||
- Implement custom form validation - use the specified validation library
|
||||
...
|
||||
```
|
||||
|
||||
## Process Checklist
|
||||
|
||||
- [ ] Complete Design & Data Flow Analysis
|
||||
- [ ] Create Structure Plan
|
||||
- [ ] Create Skeleton Files with Documentation
|
||||
- [ ] Develop Implementation Guide
|
||||
- [ ] Review and Finalize Feature Building Documents
|
||||
- [ ] Implement Feature Following Guide
|
||||
- [ ] Review Implementation Against Requirements
|
||||
|
||||
By following this standardized feature building process, we ensure that features are implemented
|
||||
consistently, with clear documentation, and according to best practices.
|
||||
|
||||
## Getting Started
|
||||
|
||||
To start building a new feature using this process, use the
|
||||
[Feature Building Template](./FEATURE_BUILDING_TEMPLATE.md) as a starting point. This template
|
||||
provides a structured document that you can fill in with the specific details for your feature.
|
||||
@@ -0,0 +1,239 @@
|
||||
# Feature Building: [Feature Name]
|
||||
|
||||
> This is a template for the Feature Building process. Replace placeholder text with actual content
|
||||
> for your feature.
|
||||
|
||||
## 1. Design and Data Flow Analysis
|
||||
|
||||
### Design Analysis
|
||||
|
||||
#### UI Components
|
||||
|
||||
- Component 1: [Description, states, interactions]
|
||||
- Component 2: [Description, states, interactions]
|
||||
- ...
|
||||
|
||||
#### Interactions and Animations
|
||||
|
||||
- Interaction 1: [Description]
|
||||
- Animation 1: [Description]
|
||||
- ...
|
||||
|
||||
#### Responsive Behavior
|
||||
|
||||
- Mobile: [Description]
|
||||
- Tablet: [Description]
|
||||
- Desktop: [Description]
|
||||
|
||||
#### Accessibility Considerations
|
||||
|
||||
- [List accessibility requirements]
|
||||
|
||||
### Data Flow Analysis
|
||||
|
||||
#### Data Requirements
|
||||
|
||||
- Data Entity 1: [Properties, validation rules]
|
||||
- Data Entity 2: [Properties, validation rules]
|
||||
- ...
|
||||
|
||||
#### API Endpoints
|
||||
|
||||
- Endpoint 1: `[METHOD] /path` - [Purpose, request/response format]
|
||||
- Endpoint 2: `[METHOD] /path` - [Purpose, request/response format]
|
||||
- ...
|
||||
|
||||
#### State Management
|
||||
|
||||
- Global State: [What needs to be in global state]
|
||||
- Local State: [What can be kept in component state]
|
||||
- Derived State: [What can be computed from other state]
|
||||
|
||||
#### Data Transformations
|
||||
|
||||
- [Describe any transformations needed between API and UI]
|
||||
|
||||
#### Caching/Persistence
|
||||
|
||||
- [Describe caching or persistence requirements]
|
||||
|
||||
## 2. Structure Planning
|
||||
|
||||
### Routing
|
||||
|
||||
#### Routes
|
||||
|
||||
- `/route1`: [Purpose, parameters]
|
||||
- `/route2`: [Purpose, parameters]
|
||||
- ...
|
||||
|
||||
#### Layouts
|
||||
|
||||
- Route 1 Layout: [Description]
|
||||
- Route 2 Layout: [Description]
|
||||
- ...
|
||||
|
||||
#### Access Control
|
||||
|
||||
- [Describe any route guards or access control]
|
||||
|
||||
### Component Hierarchy
|
||||
|
||||
```
|
||||
ParentComponent
|
||||
├── ChildComponent1
|
||||
│ ├── GrandchildComponent1
|
||||
│ └── GrandchildComponent2
|
||||
└── ChildComponent2
|
||||
```
|
||||
|
||||
#### Component Interfaces
|
||||
|
||||
- Component 1 Props: [Props description]
|
||||
- Component 2 Props: [Props description]
|
||||
- ...
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
feature-name/
|
||||
├── index.ts
|
||||
├── types.ts
|
||||
├── components/
|
||||
│ ├── ComponentOne.tsx
|
||||
│ └── ComponentTwo.tsx
|
||||
├── hooks/
|
||||
│ └── useFeatureData.ts
|
||||
└── utils/
|
||||
└── featureUtils.ts
|
||||
```
|
||||
|
||||
#### New Files to Create
|
||||
|
||||
- `feature-name/index.ts`: [Purpose]
|
||||
- `feature-name/types.ts`: [Purpose]
|
||||
- ...
|
||||
|
||||
## 3. File Skeletons
|
||||
|
||||
### `feature-name/index.ts`
|
||||
|
||||
````typescript
|
||||
/**
|
||||
* @module FeatureName
|
||||
* @description [Brief description of the feature]
|
||||
*
|
||||
* This module exports the main components and hooks for the [Feature Name] feature.
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* import { FeatureComponent } from '@/features/feature-name';
|
||||
*
|
||||
* function MyComponent() {
|
||||
* return <FeatureComponent />;
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
|
||||
export * from './components/ComponentOne';
|
||||
// Add additional exports
|
||||
````
|
||||
|
||||
### `feature-name/components/ComponentOne.tsx`
|
||||
|
||||
````typescript
|
||||
/**
|
||||
* @component ComponentOne
|
||||
* @description [Description of the component]
|
||||
*
|
||||
* Requirements:
|
||||
* - [Requirement 1]
|
||||
* - [Requirement 2]
|
||||
* - ...
|
||||
*
|
||||
* States:
|
||||
* - Loading: [Description]
|
||||
* - Error: [Description]
|
||||
* - Success: [Description]
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <ComponentOne prop1="value" />
|
||||
* ```
|
||||
*/
|
||||
|
||||
// Implementation details will go here
|
||||
````
|
||||
|
||||
### [Add skeleton documentation for all planned files]
|
||||
|
||||
## 4. Implementation Guide
|
||||
|
||||
### Implementation Order
|
||||
|
||||
1. Create `types.ts` with all required interfaces
|
||||
2. Implement API utilities and hooks
|
||||
3. Implement base UI components
|
||||
4. Implement container components
|
||||
5. Connect components to data sources
|
||||
6. Implement routing and navigation
|
||||
|
||||
### Critical Requirements
|
||||
|
||||
#### Performance
|
||||
|
||||
- [List performance requirements]
|
||||
|
||||
#### Accessibility
|
||||
|
||||
- [List accessibility requirements]
|
||||
|
||||
#### Compatibility
|
||||
|
||||
- [List browser/device compatibility requirements]
|
||||
|
||||
#### Error Handling
|
||||
|
||||
- [List error handling expectations]
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
#### Unit Tests
|
||||
|
||||
- Component 1: [Test scenarios]
|
||||
- Component 2: [Test scenarios]
|
||||
- ...
|
||||
|
||||
#### Integration Tests
|
||||
|
||||
- [List integration test scenarios]
|
||||
|
||||
#### E2E Tests
|
||||
|
||||
- [List E2E test scenarios]
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
- ❌ [Anti-pattern 1]
|
||||
- ❌ [Anti-pattern 2]
|
||||
- ...
|
||||
|
||||
### Review Checklist
|
||||
|
||||
- [ ] Code follows project style guide
|
||||
- [ ] Components are properly documented
|
||||
- [ ] All critical requirements are met
|
||||
- [ ] Tests cover main functionality
|
||||
- [ ] Accessibility guidelines are followed
|
||||
- [ ] Performance is satisfactory
|
||||
- [ ] Error handling is comprehensive
|
||||
|
||||
## Process Checklist
|
||||
|
||||
- [ ] Complete Design & Data Flow Analysis
|
||||
- [ ] Create Structure Plan
|
||||
- [ ] Create Skeleton Files with Documentation
|
||||
- [ ] Develop Implementation Guide
|
||||
- [ ] Review and Finalize Feature Building Documents
|
||||
- [ ] Implement Feature Following Guide
|
||||
- [ ] Review Implementation Against Requirements
|
||||
@@ -0,0 +1,89 @@
|
||||
# Snowball Tools Project Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
This document consolidates project standards, documentation guidelines, and best practices for the
|
||||
Snowball Tools project.
|
||||
|
||||
## Project Purpose and Standards
|
||||
|
||||
### Core Principles
|
||||
|
||||
1. **Consistency** - Establish consistent patterns across the codebase
|
||||
2. **Onboarding** - Help new developers understand project conventions
|
||||
3. **Maintainability** - Make code easier to maintain and extend
|
||||
4. **Quality** - Encourage best practices that lead to higher quality code
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### TSDoc and TypeDoc
|
||||
|
||||
We use [TSDoc](https://tsdoc.org/) for documenting TypeScript code and
|
||||
[TypeDoc](https://typedoc.org/) for generating API documentation.
|
||||
|
||||
#### Basic Comment Structure
|
||||
|
||||
TSDoc comments start with `/**` and end with `*/`:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* This is a TSDoc comment.
|
||||
*/
|
||||
```
|
||||
|
||||
#### Common TSDoc Tags
|
||||
|
||||
| Tag | Description |
|
||||
| ----------------------------------- | ----------------------------------------- |
|
||||
| `@param` | Documents a function parameter |
|
||||
| `@returns` | Documents the return value |
|
||||
| `@throws` | Documents exceptions that might be thrown |
|
||||
| `@example` | Provides an example of usage |
|
||||
| `@remarks` | Adds additional information |
|
||||
| `@deprecated` | Marks an item as deprecated |
|
||||
| `@see` | Refers to related documentation |
|
||||
| `@public`, `@protected`, `@private` | Visibility modifiers |
|
||||
|
||||
### Documentation Best Practices
|
||||
|
||||
1. **Document Public APIs**: Always document public APIs thoroughly
|
||||
2. **Include Examples**: Provide examples for complex functions or classes
|
||||
3. **Be Concise**: Keep documentation clear and to the point
|
||||
4. **Use Proper Grammar**: Use proper grammar and punctuation
|
||||
5. **Update Documentation**: Keep documentation in sync with code changes
|
||||
6. **Document Parameters**: Document all parameters, including their types and purpose
|
||||
7. **Document Return Values**: Document what a function returns
|
||||
8. **Document Exceptions**: Document any exceptions that might be thrown
|
||||
|
||||
## Generating Documentation
|
||||
|
||||
Generate documentation:
|
||||
|
||||
```bash
|
||||
yarn docs
|
||||
```
|
||||
|
||||
Watch and regenerate documentation:
|
||||
|
||||
```bash
|
||||
yarn docs:watch
|
||||
```
|
||||
|
||||
## Contributing to Standards
|
||||
|
||||
To suggest changes or additions to project standards:
|
||||
|
||||
1. Discuss proposed changes with the team
|
||||
2. Update the relevant documentation
|
||||
3. Provide examples demonstrating the benefits of the proposed changes
|
||||
|
||||
## Enforcement
|
||||
|
||||
While these standards are not automatically enforced, developers are encouraged to follow them, and
|
||||
code reviewers should check for adherence to these guidelines.
|
||||
|
||||
## Resources
|
||||
|
||||
- [TSDoc Official Documentation](https://tsdoc.org/)
|
||||
- [TypeDoc Official Documentation](https://typedoc.org/)
|
||||
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
|
||||
@@ -0,0 +1,128 @@
|
||||
# React Component Organization Conventions
|
||||
|
||||
## Feature-Based Organization
|
||||
|
||||
Group related components into feature folders:
|
||||
|
||||
```
|
||||
src/
|
||||
features/
|
||||
navigation/ # Feature group
|
||||
README.md # Feature documentation with architecture diagrams
|
||||
page-header/ # Component
|
||||
page-wrapper/ # Component
|
||||
sidebar/ # Component
|
||||
auth/ # Another feature group
|
||||
dashboard/ # Another feature group
|
||||
```
|
||||
|
||||
## Component Folder Structure
|
||||
|
||||
For each component that requires co-located files (types, tests, etc.):
|
||||
|
||||
```
|
||||
component-name/
|
||||
- ComponentName.tsx # Main component implementation
|
||||
- types.ts # Component-specific types
|
||||
- ComponentName.test.tsx # Component tests
|
||||
- README.md # Component-specific documentation
|
||||
- index.ts # Barrel exports
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- **Folders**: Use kebab-case (`page-header/`)
|
||||
- **Component Files**: Use PascalCase matching export name (`PageHeader.tsx`)
|
||||
- **Type Files**: Use `types.ts` for component-specific types
|
||||
- **Test Files**: Use component name with `.test.tsx` suffix (`PageHeader.test.tsx`)
|
||||
- **Index Files**: Always use `index.ts` for barrel exports
|
||||
|
||||
## Styling Conventions
|
||||
|
||||
- **Use Tailwind**: Always use Tailwind classes for styling instead of CSS files or inline styles
|
||||
- **Use UI Components**: Leverage existing UI components from `components/ui` directory
|
||||
- **No External CSS**: Never import external CSS files
|
||||
- **No New Libraries**: Do not add new dependencies; use existing ones
|
||||
- **Follow Patterns**: Match styling patterns used in the existing codebase
|
||||
|
||||
## Export Patterns
|
||||
|
||||
**Component File (PageHeader.tsx)**:
|
||||
```typescript
|
||||
export interface PageHeaderProps {
|
||||
title: string;
|
||||
subtitle?: string;
|
||||
}
|
||||
|
||||
export const PageHeader = ({ title, subtitle }: PageHeaderProps) => {
|
||||
return (
|
||||
// Component implementation
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
**Types File (types.ts)**:
|
||||
```typescript
|
||||
export interface PageHeaderTheme {
|
||||
backgroundColor: string;
|
||||
textColor: string;
|
||||
}
|
||||
|
||||
// Additional component-specific types
|
||||
```
|
||||
|
||||
**Barrel File (index.ts)**:
|
||||
```typescript
|
||||
export * from './PageHeader';
|
||||
export * from './types';
|
||||
```
|
||||
|
||||
## Import Examples
|
||||
|
||||
```typescript
|
||||
// Import specific component
|
||||
import { PageHeader } from '../components/page-header/PageHeader';
|
||||
|
||||
// Import via barrel
|
||||
import { PageHeader, PageHeaderTheme } from '../components/page-header';
|
||||
```
|
||||
|
||||
## Feature Documentation
|
||||
|
||||
Each feature folder should include a comprehensive README.md:
|
||||
|
||||
```markdown
|
||||
# Navigation Components
|
||||
|
||||
## Overview
|
||||
This module contains all navigation-related components for the application.
|
||||
|
||||
## Architecture
|
||||
```mermaid
|
||||
graph TD
|
||||
App --> PageWrapper
|
||||
PageWrapper --> PageHeader
|
||||
PageWrapper --> Sidebar
|
||||
PageWrapper --> MainContent
|
||||
PageHeader --> Breadcrumbs
|
||||
PageHeader --> UserMenu
|
||||
```
|
||||
|
||||
## Components
|
||||
- **PageHeader**: Application header with navigation controls
|
||||
- **PageWrapper**: Layout wrapper for all pages
|
||||
- **Sidebar**: Main navigation sidebar
|
||||
```
|
||||
|
||||
## Benefits of this Approach
|
||||
|
||||
- Avoids "index.tsx maze" - component location is always clear
|
||||
- Easier debugging (stack traces point to actual component files)
|
||||
- Feature-based organization provides clear domain boundaries
|
||||
- Architecture documentation with visual diagrams improves onboarding
|
||||
- Maintains logical co-location while separating concerns
|
||||
- Enables precise imports when needed
|
||||
- Follows widely accepted React community standards
|
||||
- Scales well with large component libraries
|
||||
|
||||
This convention balances maintainability with developer experience and remains effective as your application grows.
|
||||
Reference in New Issue
Block a user