257 lines
7.5 KiB
Markdown
257 lines
7.5 KiB
Markdown
# 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*
|