refactor: configure path aliases for absolute imports (src/@)

[kitikonti]

Background

During the code review of ZoomModeSelector.tsx, ChartPreview.tsx, and SplitPane.tsx (worktree review-layout-export-02), the following finding was raised:

[F001] NOTE: Relative imports (../common/RadioOptionCard, ../../utils/export/types, ../../styles/design-tokens) are used throughout the project instead of absolute src/-based paths, as recommended by the OwnChart patterns checklist.

The fix was deliberately deferred because no path alias infrastructure is currently configured. This issue tracks the work to set that up.

---

Problem

Relative imports are fragile under refactoring. Moving or renaming a file requires updating every relative path in it and every relative path pointing to it. With absolute imports, the path is stable regardless of where the file lives.

Example — current:

import { RadioOptionCard } from "../common/RadioOptionCard";
import type { ExportZoomMode } from "../../utils/export/types";
import { COLORS } from "../../styles/design-tokens";

Example — after this change:

import { RadioOptionCard } from "@/components/common/RadioOptionCard";
import type { ExportZoomMode } from "@/utils/export/types";
import { COLORS } from "@/styles/design-tokens";

Current nesting depth across the codebase

Most imports are 1–2 levels deep (../, ../../), which is not yet painful. The issue becomes real when files are moved into deeper subdirectories or when the project grows.

---

Why deferred

• The problem is DX-only — zero runtime/bundle/user-facing impact
• Current max nesting (2 levels) is below the threshold where it actively hurts
• Retrofitting 100+ files is a non-trivial mechanical change with real rename-collision risk
• Solo project: less benefit than for a team where multiple devs move files frequently
• Best ROI: set this up at project start, or fold it into a larger build-config change

---

Implementation Plan

1. tsconfig.json — add path alias

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

2. vite.config.ts — mirror the alias for the bundler

import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
    },
  },
  // ... rest of config
});

3. Mass-replace relative imports in src/

Use a codemod or IDE bulk-replace to rewrite all ../ imports to @/ paths.

Suggested approach:

# Preview scope
grep -r "from ['\"]\.\./" src/ --include="*.ts" --include="*.tsx" | wc -l

Then use VS Code "Replace in Files" or a sed/ts-morph script to migrate.

4. Verify

npm run type-check   # no new errors
npm run build        # bundler resolves aliases correctly
npm run test:unit    # no broken imports in tests

Note: Test files in tests/ that import from src/ via relative paths also need updating.

---

Acceptance Criteria

• tsconfig.json has baseUrl + paths for @/*
• vite.config.ts has matching resolve.alias
• All ../ and ../../ imports in src/ replaced with @/ equivalents
• npm run ci:local passes green
• No new lint warnings introduced

---

Notes

• The OwnChart patterns checklist (Issue Systematic code review and cleanup process (file-by-file) #44) flags this under Import Organisation: "Prüfe dass absolute Imports von src/ verwendet werden (nicht relative Pfade wie ../../../)"
• Since the checklist example targets 3+-level deep paths and the codebase currently stays at ≤2 levels, this is not urgent
• Good candidate to batch with any other build-config work (e.g., adding another Vite plugin, migrating to monorepo)