feat: implement hierarchical tags system with categories and subcategories

[gor3a]

Hierarchical Tags Implementation

Overview

This PR implements a comprehensive hierarchical tags system for AgileSpace, allowing users to organize issue types into categories and subcategories for better session tracking and reporting.

🎯 Features Added

Database Schema

• Tag Hierarchy: Added parent_id, tag_type, sort_order, and is_system fields to tags table
• Foreign Key Relationships: Proper parent-child relationships with cascade deletion
• Performance Indexes: Optimized queries for hierarchical data

Predefined Issue Types

• Meeting Category: Demo, Daily Stand-up, Retrospective, Sprint Planning, etc.
• Development Category: Bugs, Feature Development, Code Review, Testing, Documentation
• Project Management Category: Scrum, Product Issues, Planning, Coordination

UI Components

• HierarchicalTagSelector: Two-level tag selection (category → subcategory)
• HierarchicalTagForm: Create/edit categories and subcategories
• Collapsible Tag Management: Expandable category view with subcategory tables

Hooks & Logic

• useHierarchicalTagManagement: Complete CRUD operations for hierarchical tags
• useHierarchicalTagSelector: Tag selection logic with category expansion
• Seed Functionality: One-click setup of predefined issue types

🔧 Technical Implementation

Code Organization

• Separation of Concerns: UI components handle rendering, hooks handle logic
• Custom Hooks: Reusable tag management and selection logic
• Type Safety: Full TypeScript support with proper interfaces
• Database Queries: Optimized queries for hierarchical data fetching

Cursor Rules

Added comprehensive development guidelines:

• AgileSpace Patterns: Architecture and component structure
• Custom Hooks Best Practices: Hook patterns and conventions
• Separation of Concerns: UI/logic separation rules
• Unused Code Prevention: Code quality enforcement

🚀 User Experience

Tag Management

• Visual Hierarchy: Clear category/subcategory organization
• System Tags: Predefined tags marked as system-managed
• Sort Order: Customizable display order for tags
• Bulk Operations: Expand/collapse all categories

Session Creation

• Intuitive Selection: Two-step process (category → subcategory)
• Visual Feedback: Color-coded tags with proper contrast
• Selected Tags Display: Clear indication of chosen issue types

�� Database Changes

-- New fields added to tags table
ALTER TABLE tags 
ADD COLUMN parent_id UUID REFERENCES tags(id) ON DELETE CASCADE,
ADD COLUMN tag_type TEXT CHECK (tag_type IN ('category', 'subcategory')) DEFAULT 'subcategory',
ADD COLUMN sort_order INTEGER DEFAULT 0,
ADD COLUMN is_system BOOLEAN DEFAULT false;

-- Performance indexes
CREATE INDEX idx_tags_parent_id ON tags(parent_id);
CREATE INDEX idx_tags_tag_type ON tags(tag_type);
CREATE INDEX idx_tags_sort_order ON tags(sort_order);
CREATE INDEX idx_tags_is_system ON tags(is_system);

🧪 Testing

Manual Testing Checklist

• Create categories and subcategories
• Edit existing tags
• Delete categories (cascades to subcategories)
• Seed predefined issue types
• Select tags in session creation
• End session with selected tags
• Expand/collapse category views
• Sort order functionality

Backward Compatibility

• Existing tags automatically converted to subcategories
• No data loss during migration
• Existing sessions continue to work

�� Files Changed

New Files

• src/components/hierarchical-tag-form.tsx
• src/components/hierarchical-tag-selector.tsx
• src/constants/issue-types.ts
• src/hooks/use-hierarchical-tag-management.ts
• src/hooks/use-hierarchical-tag-selector.ts
• supabase/migrations/20250719004549_add_hierarchy_to_tags.sql
• .cursor/rules/*.mdc (development guidelines)

Modified Files

• src/components/end-session-dialog.tsx - Updated to use hierarchical selector
• src/hooks/api/use-tags.ts - Added seeding functionality
• src/lib/supabase/mutations.ts - Enhanced tag CRUD operations
• src/lib/supabase/queries.ts - Added hierarchical queries
• src/routes/space/$slug/tags/index.tsx - Complete UI overhaul
• src/types/database.types.ts - Updated schema types
• src/types/index.ts - Added hierarchical tag interfaces

�� UI/UX Improvements

• Collapsible Interface: Clean category organization
• Color Coding: Visual distinction between categories and subcategories
• System Tags: Clear indication of predefined vs custom tags
• Responsive Design: Works well on different screen sizes
• Accessibility: Proper ARIA labels and keyboard navigation

🔮 Future Enhancements

• Tag usage analytics and reporting
• Bulk tag operations
• Tag templates for different project types
• Integration with GitHub issue labels
• Advanced filtering and search

�� Migration Notes

1. Run the database migration: pnpm supabase db push
2. Existing tags will be automatically converted to subcategories
3. Use "Seed Issue Types" button to add predefined categories
4. No manual intervention required for existing data

---

Breaking Changes: None - fully backward compatible
Performance Impact: Minimal - optimized queries with proper indexing
Security: No changes to authentication or authorization

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
agilespace	❌ Failed (Inspect)			Jul 19, 2025 1:27am

[cloudflare-workers-and-pages]

Deploying agilespace with    Cloudflare Pages

Latest commit:	87804b5
Status:	✅  Deploy successful!
Preview URL:	https://b5643d1b.agilespace.pages.dev
Branch Preview URL:	https://feat-hierarchical-tags-imple.agilespace.pages.dev

View logs