refactor: separate GNOME-specific code for multiplatform support

docs/README.md

@@ -0,0 +1,83 @@
+# Do It - Developer Documentation
+
+This document provides an overview of the Do It project architecture and how to navigate its source code.
+
+## Project Overview
+
+**Do It** is a GNOME task manager application written in TypeScript, now being refactored for multiplatform support. The codebase follows a clean architecture pattern that separates platform-specific code from core business logic.
+
+## Architecture
+
+```
+src/
+├── core/           # Platform-agnostic business logic & interfaces
+├── platform/      # Platform-specific implementations
+│   ├── gnome/      # GNOME/GTK4/Adw implementation
+│   └── web/        # Web platform (future)
+├── hooks/          # Reusable hooks (mostly platform-agnostic)
+├── utils/          # Utility functions
+└── *.ts            # App entry points and shared types
+```
+
+## Key Concepts
+
+### Core Layer (`src/core/`)
+
+Contains platform-agnostic interfaces and implementations:
+
+- **interfaces/**: Abstract interfaces for settings, persistence, and task views
+- **persistence/**: Data storage implementations
+
+### Platform Layer (`src/platform/`)
+
+Contains platform-specific implementations:
+
+- Each platform has its own subfolder with platform-specific code
+- Platforms expose a public API via `index.ts`
+
+### Shared Types (`src/`)
+
+- `app.types.ts`: Core types like `ITask`, `IProject`
+- `app.enums.ts`: Shared enums like `SortingField`, `SortingStrategy`
+- `app.strings.ts`: Localized strings
+- `app.static.ts`: Static configuration
+
+## Platform-Specific Documentation
+
+- [GNOME Platform](platform-gnome.md) - Current active platform
+- [Web Platform](platform-web.md) - Future web implementation
+
+## Development Guidelines
+
+### Adding a New Platform
+
+1. Create `src/platform/<platform-name>/`
+2. Implement core interfaces (`ISettings`, `IPersistence`, `ITaskView`)
+3. Create UI components using platform-specific frameworks
+4. Export public API via `index.ts`
+5. Add to build system (Meson for GNOME, Vite/Webpack for web)
+
+### Dependency Injection
+
+The project uses factory patterns for dependency injection. Core interfaces should never import platform-specific code.
+
+### Import Aliases
+
+The project uses TypeScript path aliases:
+
+- `~core` → `src/core`
+- `~gnome` → `src/platform/gnome`
+- `~web` → `src/platform/web`
+- `~hooks` → `src/hooks`
+- `~utils` → `src/utils`
+- `~actions` → `src/platform/gnome/actions`
+
+## Building
+
+- **GNOME**: Use Meson (`meson setup build && ninja -C build`)
+- **Web**: Use Vite (future)
+
+## Resources
+
+- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/)
+- [Adwaita Widgets](https://gnome.pages.gitlab.gnome.org/libadwaita/)

docs/core.md

@@ -0,0 +1,136 @@
+# Core Layer Documentation
+
+The `src/core/` directory contains platform-agnostic business logic and interfaces that can be shared across all platforms.
+
+## Directory Structure
+
+```
+src/core/
+├── interfaces/
+│   ├── settings.ts      # Settings abstraction
+│   ├── persistence.ts   # Data persistence abstraction
+│   └── task-view.ts     # Task view abstraction
+└── persistence/
+    └── file-persistence.ts  # File-based persistence implementation
+```
+
+## Interfaces
+
+### ISettings (`interfaces/settings.ts`)
+
+Abstract interface for application settings. Platforms must implement this to provide persistent key-value storage.
+
+```typescript
+export interface ISettings {
+  get_int(key: string): number;
+  set_int(key: string, value: number): void;
+  get_string(key: string): string;
+  set_string(key: string, value: string): void;
+  get_enum(key: string): number;
+  set_enum(key: string, value: number): void;
+}
+```
+
+**Implementations:**
+
+- GNOME: `src/hooks/settings.ts` (uses `Gio.Settings`)
+
+### IPersistence (`interfaces/persistence.ts`)
+
+Abstract interface for task data persistence. Defines async load/save operations.
+
+```typescript
+import type { ITask } from '../../app.types.js';
+
+export interface IPersistence {
+  load(): Promise<ITask[]>;
+  save(tasks: ITask[]): Promise<void>;
+}
+```
+
+**Implementations:**
+
+- GNOME: `src/core/persistence/file-persistence.ts` (file-based JSON)
+- Web (planned): IndexedDB
+
+### ITaskView (`interfaces/task-view.ts`)
+
+Abstract interface for task display widgets. Provides a bridge between task data and UI components.
+
+```typescript
+import type { ITask } from '../../app.types.js';
+
+export interface ITaskView {
+  taskId: number;
+  title: string;
+  done: boolean;
+  deleted: boolean;
+  project: string;
+  created: string;
+
+  update(task: ITask): void;
+  onTaskUpdated(callback: (task: ITask) => void): void;
+  onTaskDeleted(callback: (task: ITask) => void): void;
+  to_object(): ITask;
+}
+```
+
+**Implementations:**
+
+- GNOME: `src/platform/gnome/views/task-item.ts`
+
+## Implementations
+
+### FilePersistence (`persistence/file-persistence.ts`)
+
+File-based JSON persistence implementation for GNOME.
+
+```typescript
+import type { ITask } from '../../app.types.js';
+import type { IPersistence } from '../interfaces/persistence.js';
+
+export class FilePersistence implements IPersistence {
+  // Loads tasks from JSON file
+  async load(): Promise<ITask[]>;
+
+  // Saves tasks to JSON file
+  async save(tasks: ITask[]): Promise<void>;
+}
+```
+
+## Design Principles
+
+### Platform Agnostic
+
+The core layer must never import platform-specific code:
+
+- No GTK, Adw, Gio imports
+- No browser-specific APIs
+- Only TypeScript types and interfaces
+
+### Dependency Injection
+
+Platforms inject their implementations:
+
+```typescript
+// Example: Creating platform-specific instances
+let settings: ISettings;
+let persistence: IPersistence;
+
+if (platform === 'gnome') {
+  settings = new GnomeSettings();
+  persistence = new FilePersistence();
+} else if (platform === 'web') {
+  settings = new WebSettings();
+  persistence = new IndexedDBPersistence();
+}
+```
+
+### Extensibility
+
+To add a new interface:
+
+1. Create `src/core/interfaces/<name>.ts`
+2. Define TypeScript interface
+3. Implement in each platform
+4. Document in this file

docs/hooks-utils.md

@@ -0,0 +1,125 @@
+# Hooks and Utils Documentation
+
+This document describes the helper functions and utilities in `src/hooks/` and `src/utils/`.
+
+## Hooks (`src/hooks/`)
+
+Hooks are reusable functions that provide platform-agnostic functionality. They should remain free of platform-specific imports.
+
+### tasks.sort.ts
+
+Provides task sorting functionality.
+
+```typescript
+// Sorts tasks by specified field and strategy
+sortTasks(tasks: ITask[], field: SortingField, strategy: SortingStrategy): ITask[]
+```
+
+**Dependencies:**
+
+- Imports `ITask` from `app.types`
+- Uses `ITaskView` from core interfaces (for comparison)
+
+### settings.ts
+
+> ⚠️ **Note**: This hook currently uses GNOME-specific `Gio.Settings`.
+
+```typescript
+// Provides access to application settings
+getSettings(): ISettings
+```
+
+**Status:** Needs abstraction for web platform.
+
+### autocomplete.ts
+
+Provides project name autocomplete suggestions.
+
+```typescript
+// Returns matching project names
+getSuggestions(input: string): string[]
+```
+
+## Utils (`src/utils/`)
+
+Utility functions, some platform-specific.
+
+### application.js
+
+GNOME application bootstrap.
+
+```javascript
+// Returns path to UI template
+get_template_path(filename: string): string
+
+// Initializes the GTK application
+activate(application: Gtk.Application): void
+```
+
+**Platform:** GNOME only
+
+### project-manager.ts
+
+Manages project CRUD operations.
+
+```typescript
+class ProjectManager {
+  getProjects(): string[];
+  addProject(name: string): void;
+  removeProject(name: string): void;
+}
+```
+
+**Platform:** GNOME (uses Adw/Gtk)
+
+### persistence.ts
+
+Legacy persistence utilities.
+
+> ⚠️ **Note**: Should migrate to use `core/persistence/file-persistence.ts`
+
+### log-manager.ts
+
+Logging utilities.
+
+```typescript
+class LogManager {
+  debug(message: string): void;
+  info(message: string): void;
+  error(message: string): void;
+}
+```
+
+## Guidelines
+
+### Keeping Hooks Platform-Agnostic
+
+When modifying hooks:
+
+1. **DO**: Use interfaces from `src/core/interfaces/`
+2. **DO**: Import types from `src/app.types.ts`
+3. **DON'T**: Import GTK, Adw, Gio, or browser APIs
+4. **DON'T**: Import from `src/platform/gnome/`
+
+### Example: Refactoring for Platform Agnosticism
+
+Before (GNOME-specific):
+
+```typescript
+import { Settings } from 'gi://Gio';
+
+export function getSettings() {
+  return new Settings({ schema: 'io.github.andrepg.Doit' });
+}
+```
+
+After (Platform-agnostic):
+
+```typescript
+import type { ISettings } from '~core/interfaces/settings';
+
+export function createSettings(): ISettings {
+  // Platform-specific implementation injected
+  return platform.createSettings();
+}
+```