From bd0ac0d95b0ddd778fd4bc37bb8f34d774dce7ac Mon Sep 17 00:00:00 2001 From: serversdwn Date: Tue, 25 Nov 2025 23:26:47 +0000 Subject: [PATCH] updated docs --- CHANGELOG.md | 64 ++++++++++++++++++++++++++++++++++++++++ README.md | 82 +++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 129 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 68585c9..30f9e5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,70 @@ All notable changes to TESSERACT will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.1.6] - 2025-01-25 + +### Added +- **Dynamic Status Management System** + - Per-project customizable status workflows (replacing hardcoded statuses) + - New default statuses: `backlog`, `in_progress`, `on_hold`, `done` (removed `blocked`) + - Project Settings modal with comprehensive status management: + - Drag-and-drop status reordering + - Add new custom statuses + - Rename existing statuses (inline editing) + - Delete unused statuses with validation + - Task count display per status + - Warning dialogs when attempting to delete statuses with tasks + - Settings button (⚙️) in project header to access configuration + - Status validation in backend CRUD operations + - Database migration for `projects.statuses` JSON column + +- **Enhanced Task Creation** + - Status selector dropdown in TaskForm component + - Select status when creating tasks (no longer defaults to "backlog" only) + - Works across Tree View and Kanban View + - Defaults to current column status in Kanban View + - Defaults to "backlog" in Tree View + +- **Subtask Creation in Kanban View** + - "+" button on task cards to add subtasks directly in Kanban + - Button appears on hover next to task menu + - Opens TaskForm with status defaulted to current column + - Automatically expands parent card after creating subtask + - Full parity with Tree View subtask functionality + +### Changed +- Removed hardcoded status enums from backend (`TaskStatus` enum removed) +- Task status field changed from Enum to String in database +- All status references now dynamic (backend, frontend, Kanban UI) +- Status formatting helpers added for consistent display +- Status colors now pattern-matched based on status names +- Existing tasks migrated from uppercase enum format to lowercase + +### Backend Changes +- `models.py`: Added `DEFAULT_STATUSES` constant, `statuses` JSON column to Project, changed Task.status to String +- `schemas.py`: Changed status from TaskStatus enum to str, added statuses to Project schemas +- `crud.py`: Added status validation in create_task, update_task, get_tasks_by_status +- `main.py`: Added status validation to endpoints and JSON import + +### Frontend Changes +- `ProjectSettings.jsx`: New component for managing project status workflows +- `TaskForm.jsx`: Added status selector with dynamic status list +- `KanbanView.jsx`: Dynamic status columns, subtask creation, removed hardcoded STATUSES +- `TaskMenu.jsx`: Dynamic status dropdown using projectStatuses prop +- `TreeView.jsx`: Dynamic status helpers, passes statuses to forms +- `ProjectView.jsx`: Integrated ProjectSettings modal with gear icon button + +### Fixed +- Database schema migration for projects.statuses column +- Task status migration from uppercase (BACKLOG, IN_PROGRESS, DONE) to lowercase format +- 51 existing tasks successfully migrated to new status format + +### Technical Details +- New database column: `projects.statuses` (JSON, default: ["backlog", "in_progress", "on_hold", "done"]) +- Status validation at multiple layers (CRUD, API endpoints, frontend) +- Helper functions for status formatting and color coding +- Prop drilling of projectStatuses through component hierarchy + ## [0.1.5] - 2025-01-XX ### Added diff --git a/README.md b/README.md index f202e95..9599190 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **Task Decomposition Engine** - A self-hosted web application for managing deeply nested todo trees with advanced time tracking and project planning capabilities. -![Version](https://img.shields.io/badge/version-0.1.5-orange) +![Version](https://img.shields.io/badge/version-0.1.6-orange) ![License](https://img.shields.io/badge/license-MIT-blue) ## Overview @@ -15,13 +15,21 @@ TESSERACT is designed for complex project management where tasks naturally decom - **Dual View Modes**: - **Tree View**: Hierarchical collapsible tree with full nesting - **Nested Kanban**: Status-based board where parent tasks appear in multiple columns +- **Dynamic Status Workflows** (v0.1.6): + - Customizable per-project status workflows + - Drag-and-drop status reordering + - Add, rename, or delete statuses with validation + - Project Settings modal for easy configuration - **Intelligent Time Tracking**: - Leaf-based time calculation (parent times = sum of descendant leaf tasks) - Automatic exclusion of completed tasks from time estimates - Shows remaining work, not total estimated work - Auto-complete parents when all children are done -- **Rich Metadata**: Tags, time estimates, priority flags, and status tracking -- **Enhanced Task Creation**: Full-featured forms with all metadata fields upfront +- **Rich Metadata**: Tags, time estimates, priority flags, and customizable status tracking +- **Enhanced Task Creation**: + - Full-featured forms with all metadata fields upfront + - Status selector in task creation forms + - Subtask creation directly in Kanban view - **LLM Integration**: Import JSON task trees generated by AI assistants - **Real-Time Search**: Find tasks across projects with filtering - **Self-Hosted**: Full data ownership and privacy @@ -79,23 +87,43 @@ docker-compose down -v 2. Enter a project name and optional description 3. Click "Create" +### Managing Project Settings + +Click the **⚙️ Settings** button in the project header to access: + +**Status Workflow Management:** +- **View Statuses**: See all current statuses in order with task counts +- **Reorder**: Drag and drop statuses to change Kanban column order +- **Add Status**: Click "+ Add Status" to create a new custom status +- **Rename**: Click any status name to edit inline (auto-formats to lowercase_with_underscores) +- **Delete**: Click trash icon to remove unused statuses + - Cannot delete statuses that have tasks (shows warning with count) + - Cannot delete the last remaining status +- **Save**: Click "Save Changes" to apply your workflow + +**Default Statuses**: `backlog`, `in_progress`, `on_hold`, `done` + ### Managing Tasks #### Tree View **Add Root Task**: Click "+ Add Root Task" button - Enter title (required) +- Add description (optional) - Add tags (comma-separated, e.g., "frontend, bug-fix") - Set time estimate (hours and minutes) +- **Select status** (defaults to "backlog") - Choose flag color (8 colors or none) **Add Subtask**: Click the "+" icon on any task - Same full-featured form as root tasks - Creates a child of the selected task +- Status selector available **Edit Task**: Click the three-dot menu (⋮) on any task -- **Change Status**: Backlog → In Progress → Blocked → Done +- **Change Status**: Choose from your project's custom statuses - **Set Time Estimate**: Separate hours and minutes inputs +- **Edit Description**: Multi-line text area - **Edit Tags**: Comma-separated list - **Set Flag Color**: 8 colors available - **Edit Title**: Rename the task @@ -113,13 +141,22 @@ The Kanban board displays tasks in a nested hierarchy while maintaining status-b - Have distinct styling (thick orange border, bold title) - Click chevron to expand/collapse and see children in that column - Cannot be dragged (only leaf tasks are draggable) +- Click "+" button to add subtasks directly **Leaf Tasks**: - Appear only in their status column - Fully draggable between columns - Standard card styling +- Click "+" button to add subtasks (converts to parent) -**Add Task**: Click "+" in any column to create a root-level task +**Add Root Task**: Click "+" in any column header +- Opens TaskForm with status pre-selected to that column +- All metadata fields available (tags, time, flag, description) + +**Add Subtask**: Click "+" button on any task card (appears on hover) +- Opens TaskForm below the parent card +- Status defaults to current column +- Automatically expands parent after creation **Move Tasks**: Drag and drop leaf task cards between columns @@ -172,6 +209,11 @@ TESSERACT can import task hierarchies from JSON files, making it perfect for LLM ```json { + "project": { + "name": "My Project", + "description": "Project description", + "statuses": ["backlog", "in_progress", "on_hold", "done"] + }, "tasks": [ { "title": "Main Task", @@ -198,7 +240,10 @@ TESSERACT can import task hierarchies from JSON files, making it perfect for LLM } ``` -See `example-import.json` for a complete example with v0.1.4 features. +**Notes:** +- `project.statuses` is optional (defaults to: backlog, in_progress, on_hold, done) +- `status` must match one of the project's statuses +- See `example-import.json` for a complete example ### Search @@ -217,6 +262,7 @@ projects ├─ id (PK) ├─ name ├─ description +├─ statuses (JSON array, default: ["backlog", "in_progress", "on_hold", "done"]) ├─ created_at └─ updated_at @@ -226,7 +272,7 @@ tasks ├─ parent_task_id (FK → tasks.id) [self-referencing] ├─ title ├─ description -├─ status (enum: backlog, in_progress, blocked, done) +├─ status (String, validated against project.statuses) ├─ sort_order ├─ estimated_minutes (Integer) ├─ tags (JSON array) @@ -274,17 +320,18 @@ tesseract/ ├─ frontend/ │ ├─ src/ │ │ ├─ components/ -│ │ │ ├─ TreeView.jsx # Hierarchical tree -│ │ │ ├─ KanbanView.jsx # Status board -│ │ │ ├─ TaskMenu.jsx # Three-dot menu -│ │ │ ├─ TaskForm.jsx # Enhanced creation form -│ │ │ └─ SearchBar.jsx # Search component +│ │ │ ├─ TreeView.jsx # Hierarchical tree +│ │ │ ├─ KanbanView.jsx # Status board +│ │ │ ├─ ProjectSettings.jsx # Status workflow management +│ │ │ ├─ TaskMenu.jsx # Three-dot menu +│ │ │ ├─ TaskForm.jsx # Enhanced creation form +│ │ │ └─ SearchBar.jsx # Search component │ │ ├─ pages/ -│ │ │ ├─ ProjectList.jsx # Project list -│ │ │ └─ ProjectView.jsx # Project detail +│ │ │ ├─ ProjectList.jsx # Project list +│ │ │ └─ ProjectView.jsx # Project detail │ │ ├─ utils/ -│ │ │ ├─ api.js # API client -│ │ │ └─ format.js # Time/tag formatting +│ │ │ ├─ api.js # API client +│ │ │ └─ format.js # Time/tag formatting │ │ └─ App.jsx │ ├─ Dockerfile │ └─ package.json @@ -363,9 +410,10 @@ services: Ensure JSON structure matches schema. Common issues: - Missing required `title` field -- Invalid `status` values (must be: backlog, in_progress, blocked, done) +- Invalid `status` values (must match project's statuses) - Invalid `estimated_minutes` (must be positive integer) - Malformed JSON syntax +- Status not in project's status list (import validates against project.statuses) ## Roadmap