# BOQ Bundle Category-wise Preview Enhancement

**Date:** 2026-04-24
**Status:** Implemented

## Objective

Improve item selection efficiency in the BOQ Bundle creation module by grouping items by category in an accordion-style view.

---

## User Choices

| Decision | Choice |
|----------|--------|
| Layout | Inline Accordion Table |
| Sorting | Category Order + Item Number |
| Search | Global Search Only (auto-expand matching categories) |
| Category Header | Item count + Total quantity + Estimated cost |
| Expand/Collapse State | Reset to collapsed on page load |
| View Toggle | Always visible (flat list ↔ category-wise) |

---

## Layout & Structure

### Inline Accordion Table
- Replace flat table with collapsible category rows
- Each category has a header row (always visible) that expands to show items
- Header displays: Category name, item count, total quantity, estimated cost
- Expand/collapse via chevron icon or entire header click

### View Toggle
- Always visible at top of item section (tab switch or toggle)
- Two modes:
  - **Category-wise (default):** Accordion grouped view
  - **Flat list:** Current flat table view (preserved for backward compatibility)

---

## Data Grouping & Sorting

### Category Order
Categories follow a predefined display order aligned with the Project/Tender modules:
1. Civil
2. Electromechanical
3. Transmission Line
4. Control System
5. (Other categories as defined in system)

### Within-Category Sorting
Items sorted by item number (ascending) within each category.

---

## Search Behavior

### Global Search Bar
- Single search input at top of item section
- Filters across all categories simultaneously
- Matching categories auto-expand; non-matching collapse
- Clear button to reset search
- Search matches: item code, item name

---

## Category Header Details

Each category header displays (when expanded):
- Category name
- Chevron indicator (expanded/collapsed)
- Item count badge
- Total quantity sum
- Estimated cost sum (quantity × rate)

---

## Component Architecture

### New Components
1. `CategoryAccordionItem` - Reusable accordion row for a single category
2. `ItemsViewToggle` - Tab/switch for flat vs grouped view

### Modified Components
1. `ItemSelectionTable` (in `/boq/new/` and `/boq/[bundleId]/`) - Add toggle, transform into accordion

### State Management
- `selectedItems`: `{ [itemId]: { quantity, rate } }` (unchanged)
- `expandedCategories`: `Set<string>` - tracks which categories are expanded
- `searchQuery`: `string` - current search filter
- `viewMode`: `'grouped' | 'flat'` - current view mode

---

## Visual Clarity

- Clear separation between categories via:
  - Bold category headers with background color
  - Dividers between categories
  - Indentation for items within category
- Item details shown: code, name, unit, quantity (editable), est. rate, total
- Selected items have checkbox filled and subtle highlight

---

## Consistency

Category-wise structure aligns with how items are displayed in:
- Project module
- Tender module

Using existing category definitions and sort order from shared utilities.

---

## Implementation Notes

1. **Backward Compatibility:** Flat list view preserved via toggle
2. **Expand State Reset:** Categories collapsed by default on page load
3. **Search Persistence:** Search query resets when clearing
4. **Real-time Updates:** Category totals recalculate when item quantities/rates change