Cursor rule

1---
2globs:
3  - "packages/hermes-app/src/components/**/*.tsx"
4---
5 
6# Hermes App - React Components Rules
7 
8## Component Structure
9 
10```
11components/
12├── ui/              # shadcn/ui components (styled primitives)
13├── layout/          # Layout components
14├── auth/            # Authentication components
15├── download/        # Download-related components
16├── queue/           # Queue view components
17└── settings/        # Settings components
18```
19 
20## Component Definition
21 
22```typescript
23interface ComponentNameProps {
24  title: string;
25  onAction?: () => void;
26  items?: Item[];
27  className?: string;
28}
29 
30export function ComponentName({
31  title,
32  onAction,
33  items = [],
34  className,
35}: ComponentNameProps) {
36  return (
37    <div className={cn("base-classes", className)}>
38      {title}
39    </div>
40  );
41}
42```
43 
44### Rules
45- Use functional components with TypeScript
46- Component names use PascalCase
47- File names match component names
48- Export as named export, not default
49- Use hooks for state management
50- Keep components focused and single-purpose
51 
52## Props and TypeScript
53 
54### Props Definition
55```typescript
56interface ButtonProps {
57  /** The button's display text */
58  label: string;
59  /** Optional click handler */
60  onClick?: () => void;
61  /** Button visual style */
62  variant?: "primary" | "secondary" | "destructive";
63  disabled?: boolean;
64  className?: string;
65}
66 
67export function Button({
68  label,
69  onClick,
70  variant = "primary",
71  disabled = false,
72  className,
73}: ButtonProps) {
74  // Implementation
75}
76```
77 
78### Event Handlers
79- Prefix with `on`: `onClick`, `onChange`, `onSubmit`
80- Use proper event types: `React.MouseEvent`, `React.ChangeEvent`
81 
82### Children Props
83```typescript
84interface ContainerProps {
85  children: React.ReactNode;
86  className?: string;
87}
88```
89 
90## shadcn/ui Integration
91 
92### Using UI Components
93```typescript
94import { Button } from "@/components/ui/button";
95import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
96import { cn } from "@/lib/utils";
97 
98export function FeatureCard({ title, className }: Props) {
99  return (
100    <Card className={cn("w-full", className)}>
101      <CardHeader>
102        <CardTitle>{title}</CardTitle>
103      </CardHeader>
104      <CardContent>
105        <Button>Action</Button>
106      </CardContent>
107    </Card>
108  );
109}
110```
111 
112- Import from `@/components/ui/`
113- Don't modify UI component files directly
114- Compose UI components to build features
115- Use `cn()` for className merging
116 
117## Styling with Tailwind CSS
118 
119### Class Organization
120```typescript
121<div className={cn(
122  // Layout
123  "flex flex-col md:flex-row gap-4",
124  // Spacing
125  "p-4 m-2",
126  // Typography
127  "text-sm font-medium",
128  // Colors
129  "bg-background text-foreground",
130  // Effects
131  "rounded-lg shadow-md hover:shadow-lg",
132  // Conditional
133  isActive && "bg-accent",
134  className
135)}>
136```
137 
138### Theme Variables
139Use CSS variables for theme colors (support light/dark):
140```typescript
141<div className="bg-background text-foreground border-border">
142<div className="bg-primary text-primary-foreground">
143<div className="bg-muted text-muted-foreground">
144```
145 
146### Responsive Design
147```typescript
148<div className={cn(
149  "grid grid-cols-1",      // Mobile
150  "md:grid-cols-2",        // Tablet
151  "lg:grid-cols-3",        // Desktop
152  "xl:grid-cols-4"         // Large
153)}>
154```
155 
156## State Management
157 
158### Local State
159```typescript
160const [count, setCount] = useState<number>(0);
161const [items, setItems] = useState<Item[]>([]);
162 
163// Functional update
164setCount((prev) => prev + 1);
165setItems((prev) => [...prev, newItem]);
166```
167 
168### Effects
169```typescript
170useEffect(() => {
171  const subscription = subscribeToData();
172  return () => subscription.unsubscribe();
173}, [dependency]);
174```
175 
176### Server State (TanStack Query)
177```typescript
178import { useQuery } from "@tanstack/react-query";
179 
180export function DownloadList() {
181  const { data: downloads, isLoading, error } = useQuery({
182    queryKey: ["downloads"],
183    queryFn: fetchDownloads,
184  });
185 
186  if (isLoading) return <LoadingSpinner />;
187  if (error) return <ErrorDisplay error={error} />;
188 
189  return <div>{/* Render downloads */}</div>;
190}
191```
192 
193## Component Composition
194 
195### Container/Presentational Pattern
196```typescript
197// Container - handles data
198export function DownloadListContainer() {
199  const { data, isLoading } = useQuery({
200    queryKey: ["downloads"],
201    queryFn: fetchDownloads,
202  });
203  
204  const handleDelete = (id: string) => { /* ... */ };
205 
206  return (
207    <DownloadListPresentation
208      downloads={data}
209      isLoading={isLoading}
210      onDelete={handleDelete}
211    />
212  );
213}
214 
215// Presentation - pure rendering
216function DownloadListPresentation({ downloads, isLoading, onDelete }: Props) {
217  // Pure rendering logic
218}
219```
220 
221## Accessibility
222 
223### Semantic HTML
224- Use appropriate HTML elements
225- Use `<button>` for actions, `<a>` for navigation
226- Don't use `<div>` for interactive elements
227 
228### ARIA Attributes
229```typescript
230<button
231  aria-label="Delete download"
232  aria-pressed={isActive}
233  aria-disabled={isDisabled}
234>
235  <TrashIcon />
236</button>
237 
238<div role="status" aria-live="polite">
239  {statusMessage}
240</div>
241```
242 
243### Keyboard Navigation
244```typescript
245const handleKeyDown = (e: React.KeyboardEvent) => {
246  if (e.key === "Enter" || e.key === " ") {
247    e.preventDefault();
248    onClick();
249  }
250};
251```
252 
253## Performance
254 
255### Memoization
256```typescript
257import { useMemo, useCallback, memo } from "react";
258 
259// Memoize calculations
260const sortedItems = useMemo(
261  () => items.sort((a, b) => a.name.localeCompare(b.name)),
262  [items]
263);
264 
265// Memoize callbacks
266const handleClick = useCallback(() => {
267  doSomething(id);
268}, [id]);
269 
270// Memoize components
271export const ExpensiveComponent = memo(function ExpensiveComponent({ data }: Props) {
272  return <div>{/* ... */}</div>;
273});
274```
275 
276## Loading States
277 
278```typescript
279import { Skeleton } from "@/components/ui/skeleton";
280 
281if (isLoading) {
282  return <Skeleton className="h-10 w-full" />;
283}
284 
285// Conditional rendering
286{isLoading && <LoadingSpinner />}
287{error && <ErrorDisplay error={error} />}
288{data && <DataDisplay data={data} />}
289```
290 
291