one-context: Cursor rule for Claude Code

Frontend Patterns

Component Structure

• Single responsibility, under 200 lines (refactor at 300+)
• One component per file, props interface at top
• Use unions for variants ("compact" | "default" not string)
• Early returns for edge cases, logic before JSX

interface ComponentNameProps {
  variant: "compact" | "default";
  onAction: (value: string) => void;
}

export const ComponentName = ({ variant, onAction }: ComponentNameProps) => {
  if (variant === "compact") return <CompactView onAction={onAction} />;
  return <DefaultView onAction={onAction} />;
};

Naming: ComponentNameProps, ComponentNameConfig

Composition

• Container/Presentational: Container handles state, passes to presentational children
• Extract when: repeated in 2+ places, exceeds 30-40 lines, distinct responsibility
• Parent computes, child displays: Don't recalculate derived values in children
• Avoid prop drilling: Pass directly to consumers, not through intermediary wrappers

// ✅ Good: Parent calculates, child displays
const displayTime = useMemo(() => data?.naturalTime || data?.scheduledTime, [data]);
<Child displayTime={displayTime} />

// ❌ Bad: Child recalculates parent's work
const Child = ({ data }) => {
  const displayTime = data?.naturalTime || data?.scheduledTime; // Don't duplicate
}

Custom Hooks

Extract when the same useState + mutation pattern appears in 3+ components.

// hooks/[domain]/use[Domain][Action].ts
export function useManageDialog<T>(mutationFn: (item: T) => Promise<void>) {
  const [showDialog, setShowDialog] = useState(false);
  const [selectedItem, setSelectedItem] = useState<T | null>(null);

  const openDialog = (item: T) => { setSelectedItem(item); setShowDialog(true); };
  const closeDialog = () => { setShowDialog(false); setSelectedItem(null); };

  const handleConfirm = async () => {
    if (!selectedItem) return;
    await mutationFn(selectedItem);
    closeDialog();
  };

  return { showDialog, selectedItem, openDialog, closeDialog, handleConfirm };
}