Add codebase mapping documents
This commit is contained in:
256
.planning/codebase/CONVENTIONS.md
Normal file
256
.planning/codebase/CONVENTIONS.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Coding Conventions
|
||||
|
||||
**Analysis Date:** 2026-03-13
|
||||
|
||||
## Overview
|
||||
|
||||
This codebase follows conventions documented in `/sample_interface/guidelines/Guidelines.md` with React/TypeScript patterns optimized for a touchscreen industrial dashboard interface.
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
### Files
|
||||
- **Components:** PascalCase with `.tsx` extension (e.g., `RainfallView.tsx`, `Header.tsx`)
|
||||
- **Views:** `[Feature]View.tsx` pattern (e.g., `SettingView.tsx`, `LoginView.tsx`)
|
||||
- **UI Components:** Lowercase with hyphen separation (e.g., `button.tsx`, `card.tsx`)
|
||||
- **Utilities:** camelCase (e.g., `utils.ts`)
|
||||
- **Configuration:** `.config.ts` or `.config.mjs` (e.g., `vite.config.ts`, `postcss.config.mjs`)
|
||||
|
||||
### Functions & Variables
|
||||
- **Functions:** camelCase (e.g., `scrollUp()`, `toggleExpanded()`, `formatTime()`)
|
||||
- **React Components:** PascalCase (e.g., `function Card()`, `function Header()`)
|
||||
- **State Variables:** camelCase with `is`/`has`/`should` prefix for booleans
|
||||
- `const [sidebarCollapsed, setSidebarCollapsed] = useState(false)`
|
||||
- `const [isOnline, setIsOnline] = useState(true)`
|
||||
- `const [selectedFile, setSelectedFile] = useState(...)`
|
||||
- **Constants:** camelCase for objects/arrays, UPPERCASE for true constants
|
||||
- `const menuItems = [...]`
|
||||
- `const scrollAmount = 300`
|
||||
|
||||
### Props & Types
|
||||
- **Props Interface:** `[ComponentName]Props` (e.g., `SidebarProps`, `MenuItem`)
|
||||
- **Type Parameters:** PascalCase (e.g., `TFieldValues`, `TName`)
|
||||
- **Event Handlers:** `on[Action]` prefix (e.g., `onToggle`, `onClick`)
|
||||
|
||||
## Code Style
|
||||
|
||||
### Formatting
|
||||
- **No automated linting/formatting configured** (no ESLint, Prettier, or Biome detected)
|
||||
- Indentation: 2 spaces
|
||||
- Semicolons: Used consistently
|
||||
- Quotes: Double quotes for strings
|
||||
- Trailing commas: Not used consistently
|
||||
|
||||
### Component Structure
|
||||
```typescript
|
||||
// Named function declaration (preferred)
|
||||
function Button({ className, variant, ...props }: ButtonProps) {
|
||||
return <Comp className={cn(buttonVariants({ variant, className }))} {...props} />;
|
||||
}
|
||||
|
||||
// Arrow function for simpler components
|
||||
export const router = createBrowserRouter([...]);
|
||||
|
||||
// Export at end of file for UI components
|
||||
export { Button, buttonVariants };
|
||||
```
|
||||
|
||||
## Import Organization
|
||||
|
||||
### Order
|
||||
1. **React imports:** `import * as React from "react"`
|
||||
2. **External libraries:** Radix UI, React Router, Lucide icons
|
||||
3. **Internal components:** Relative paths from current file
|
||||
4. **Utilities:** Local utility functions
|
||||
|
||||
### Examples
|
||||
```typescript
|
||||
// From button.tsx
|
||||
import * as React from "react";
|
||||
import { Slot } from "@radix-ui/react-slot";
|
||||
import { cva, type VariantProps } from "class-variance-authority";
|
||||
import { cn } from "./utils";
|
||||
|
||||
// From views
|
||||
import { Card, CardContent } from "../ui/card";
|
||||
import { Button } from "../ui/button";
|
||||
import { Settings } from "lucide-react";
|
||||
```
|
||||
|
||||
### Path Aliases
|
||||
- `@/` maps to `src/` directory (configured in `vite.config.ts`)
|
||||
- Currently used in minimal places; relative imports preferred in existing code
|
||||
|
||||
## Component Patterns
|
||||
|
||||
### shadcn/ui Pattern
|
||||
Components follow the shadcn/ui design pattern:
|
||||
```typescript
|
||||
// 1. Import React as namespace
|
||||
import * as React from "react";
|
||||
|
||||
// 2. Use React.ComponentProps for HTML element props
|
||||
function Card({ className, ...props }: React.ComponentProps<"div">) {
|
||||
return (
|
||||
<div
|
||||
data-slot="card" // Data attribute for debugging
|
||||
className={cn("base-classes", className)} // cn() utility for class merging
|
||||
{...props}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
// 3. Export at end
|
||||
export { Card, CardHeader, ... };
|
||||
```
|
||||
|
||||
### View Components
|
||||
Views follow consistent structure:
|
||||
```typescript
|
||||
export function ViewName() {
|
||||
// Local state and data
|
||||
const data = [...];
|
||||
|
||||
return (
|
||||
<div className="space-y-4">
|
||||
{/* Header with icon and title */}
|
||||
<div className="flex items-center gap-3">
|
||||
<Icon className="w-6 h-6 text-blue-400" />
|
||||
<h1 className="text-2xl font-bold text-white">Title</h1>
|
||||
</div>
|
||||
|
||||
{/* Content cards */}
|
||||
<Card>...</Card>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Styling Conventions
|
||||
|
||||
### Tailwind CSS Usage
|
||||
- **Primary styling method:** Tailwind utility classes
|
||||
- **Dark theme default:** All components styled for dark UI
|
||||
- **Custom colors:** Extended via CSS variables in `theme.css`
|
||||
|
||||
### Color Palette
|
||||
- Backgrounds: `bg-gray-900` (primary), `bg-gray-950` (elevated), `bg-gray-800` (inputs)
|
||||
- Primary actions: `bg-blue-600 hover:bg-blue-700`
|
||||
- Success: `text-green-400`, Warning: `text-yellow-400`, Error: `text-red-400`
|
||||
- Borders: `border-gray-700`
|
||||
|
||||
### Class Name Utility
|
||||
All UI components use `cn()` utility from `utils.ts`:
|
||||
```typescript
|
||||
import { clsx, type ClassValue } from "clsx";
|
||||
import { twMerge } from "tailwind-merge";
|
||||
|
||||
export function cn(...inputs: ClassValue[]) {
|
||||
return twMerge(clsx(inputs));
|
||||
}
|
||||
```
|
||||
|
||||
### Touchscreen-First Design
|
||||
- Minimum touch targets: 44x44px (preferably 56x56px)
|
||||
- Button sizing: `h-14 w-14` for navigation, `h-9` for standard buttons
|
||||
- Spacing: `p-3` or `p-4` for adequate touch area
|
||||
|
||||
## State Management
|
||||
|
||||
### Local State
|
||||
- React `useState` for component-level state
|
||||
- `useEffect` for side effects (timers, subscriptions)
|
||||
- No global state management library detected
|
||||
|
||||
### Router State
|
||||
- React Router v7 for routing
|
||||
- `useLocation()` for current path
|
||||
- URL as source of truth for navigation state
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Patterns
|
||||
- Minimal explicit error handling in UI code
|
||||
- Form validation via react-hook-form (in `form.tsx`)
|
||||
- Console errors for development debugging
|
||||
|
||||
### Type Safety
|
||||
- TypeScript strict mode implied by usage
|
||||
- Type imports using `type` keyword: `import { type ClassValue }`
|
||||
- Generic components with proper type constraints
|
||||
|
||||
## Comments
|
||||
|
||||
### Guidelines
|
||||
- Minimal inline comments
|
||||
- Component purpose inferred from file name and structure
|
||||
- Complex logic may have inline explanations
|
||||
|
||||
### JSDoc/TSDoc
|
||||
- Not used extensively
|
||||
- Type definitions provide documentation
|
||||
|
||||
## Function Design
|
||||
|
||||
### Size
|
||||
- Components: Typically 30-120 lines
|
||||
- View components: 50-110 lines each
|
||||
- UI components: 20-90 lines each
|
||||
|
||||
### Parameters
|
||||
- Destructured props with explicit typing
|
||||
- Spread operator for passing through remaining props
|
||||
- Default values inline in destructuring
|
||||
|
||||
### Return Values
|
||||
- JSX.Element for React components
|
||||
- Void for event handlers
|
||||
- Typed arrays/objects for data functions
|
||||
|
||||
## Module Design
|
||||
|
||||
### Exports
|
||||
- Named exports for all components (no default exports except App.tsx)
|
||||
- Grouped exports at end of file for UI components
|
||||
- Re-exports from barrel files not used
|
||||
|
||||
### File Organization
|
||||
```
|
||||
src/app/
|
||||
├── App.tsx # Default export, entry point
|
||||
├── routes.ts # Named export for router config
|
||||
├── components/
|
||||
│ ├── [Layout].tsx # Named exports
|
||||
│ ├── ui/ # UI primitives
|
||||
│ │ └── [component].tsx
|
||||
│ └── views/ # Page views
|
||||
│ └── [View].tsx
|
||||
└── styles/
|
||||
└── *.css
|
||||
```
|
||||
|
||||
## Special Conventions
|
||||
|
||||
### Touchscreen Interface
|
||||
- No scrollbars visible (hidden via CSS)
|
||||
- Navigation via fixed Up/Down buttons
|
||||
- Fixed button positioning: `fixed top-20 right-4`
|
||||
|
||||
### Data Display Pattern
|
||||
- Icon + Title header for all views
|
||||
- Card-based content organization
|
||||
- Color-coded data categories
|
||||
|
||||
### Status Indicators
|
||||
- Icon + text pattern: `<Wifi className="w-3 h-3 text-green-500" />`
|
||||
- Dot indicators: `w-2 h-2 rounded-full`
|
||||
|
||||
## Configuration Files
|
||||
|
||||
- **`vite.config.ts`:** Build configuration with path alias
|
||||
- **`postcss.config.mjs`:** PostCSS (minimal - Tailwind handles processing)
|
||||
- **`package.json`:** Scripts limited to `build`
|
||||
- **No lint/format config detected:** No ESLint, Prettier, or Biome configuration
|
||||
|
||||
---
|
||||
|
||||
*Convention analysis: 2026-03-13*
|
||||
Reference in New Issue
Block a user