github-starred/actual
2
0
Fork 0
mirror of https://github.com/actualbudget/actual.git synced 2026-07-16 15:14:02 -05:00
Code Issues 3.0k Packages Projects Releases 58 Wiki Activity

[PR #5268] [CLOSED] [WIP] ✨ Introduce Hierarchical Category Groups #20214

New Issue
Closed
opened 2026-04-14 21:31:08 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-14 21:31:08 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/actualbudget/actual/pull/5268
Author: @Johnn27
Created: 7/2/2025
Status: ❌ Closed

Base: master ← Head: feat/sub-categories-johnn27

📝 Commits (10+)

  • 2a9e296 feat: sub category groups
  • 9d9207c chore: release note
  • 7618a39 fix: adding initial child group add budget twice to total
  • d9ec619 feat: groups for income
  • 6a7ef6f chore: rename button to "Add sub-group"
  • 9988c6e Merge remote-tracking branch 'origin/master' into feat/sub-categories
  • 3c25df1 Merge remote-tracking branch 'underkoen/feat/sub-categories' into feat/sub-categories-johnn27
  • 0247b9b Merge branch 'actualbudget:master' into feat/sub-categories-johnn27
  • 7aa6ad3 Fixing code broken from merge so it is in runnable state
  • 7f71f7d Merge branch 'feat/sub-categories-johnn27' of https://github.com/Johnn27/actual into feat/sub-categories-johnn27

📊 Changes

39 files changed (+2596 additions, -99 deletions)

View changed files

➕ docs/hierarchical-categories/README.md (+91 -0)
➕ docs/hierarchical-categories/competitive-research.md (+433 -0)
➕ docs/hierarchical-categories/implementation-spec.md (+284 -0)
➕ docs/hierarchical-categories/mixed-categories-approach.md (+227 -0)
➕ docs/hierarchical-categories/risk-analysis.md (+386 -0)
➕ docs/hierarchical-categories/user-guide.md (+75 -0)
📝 packages/component-library/src/theme.ts (+1 -0)
📝 packages/desktop-client/src/components/budget/BudgetCategories.jsx (+81 -52)
📝 packages/desktop-client/src/components/budget/BudgetTable.tsx (+1 -1)
📝 packages/desktop-client/src/components/budget/ExpenseCategory.tsx (+3 -0)
📝 packages/desktop-client/src/components/budget/ExpenseGroup.tsx (+12 -1)
📝 packages/desktop-client/src/components/budget/IncomeCategory.tsx (+3 -0)
📝 packages/desktop-client/src/components/budget/IncomeGroup.tsx (+6 -0)
📝 packages/desktop-client/src/components/budget/IncomeHeader.tsx (+5 -2)
📝 packages/desktop-client/src/components/budget/SidebarCategory.tsx (+6 -1)
📝 packages/desktop-client/src/components/budget/SidebarGroup.tsx (+16 -3)
📝 packages/desktop-client/src/components/budget/envelope/EnvelopeBudgetComponents.tsx (+3 -2)
📝 packages/desktop-client/src/components/budget/index.tsx (+18 -4)
📝 packages/desktop-client/src/components/settings/Experimental.tsx (+6 -0)
➕ packages/desktop-client/src/components/util/BuildCategoryHierarchy.test.ts (+528 -0)

...and 19 more files

📄 Description

✨ feat: Introduce Hierarchical Category Group (Draft)

This pull request introduces the 6th most voted feature of hierarchical sub-categories, allowing for more granular and organized budgeting. This work is based on the original efforts in #3772 by @underkoen, which has been updated and adapted to the current codebase.

This PR is currently in a draft stage. I am actively seeking feedback, suggestions, and guidance from the community and maintainers. I am fully open to changes and requests, and community support for this direction will determine its continuation.

🎥 Demo

chrome_BhTFKz97LW

Key Changes & Implementation Logic

The core of this implementation focuses on a robust, client-side approach to hierarchy management to prevent regressions and ensure data consistency.

  1. Client-Side Hierarchy Building: Instead of relying on the backend to return a hierarchical structure, the application now always fetches flat lists of categories and category groups. A new, dedicated helper, buildCategoryHierarchy.ts, is responsible for transforming this flat data into a nested, hierarchical structure on the front end. This approach is crucial because it allows all existing functionality, such as the category pickers in the Reports tab, to continue working with the flat structure they expect, preventing any breaking changes.

  2. Modular & Testable: The BuildCategoryHierarchy.ts helper is built with modular, single-responsibility functions, making it highly readable, maintainable, and easy to unit test (which is a key next step!).

  3. UI Integration: The BudgetCategories.jsx component now uses this new helper to build the category tree, which is then rendered by the expandGroup logic. This minimizes changes to the existing component while centralizing the complex data transformation.

Future Goals & Vision 🚀

If this initial implementation is successful and supported by the community, the end goal is to leverage this new hierarchical data structure for more advanced features, such as:

  • Sankey Diagram Report: The hierarchical data can be used to build a Sankey diagram report in #1739 (which I also want to revive).
  • Improved Reporting: Other reports could also be enhanced to support grouping (e.g. grouped bar charts).

📝 TODO & Next Steps

If this is endorsed by the maintainers, I will continue with the work below:

  • Unit Tests: Add comprehensive unit tests for the new buildCategoryHierarchy.ts helper.
  • E2E (Playwright) Tests: Create end-to-end tests to cover user interactions with sub-categories.
  • Mobile Display: Ensure the hierarchy is displayed correctly and is usable on mobile devices.
  • UI/UX Improvements: Refine the grouping order and UI behavior for a polished user experience.
  • Drag-and-Drop: Enable drag-and-drop functionality for reordering sub-groups themselves.
  • Enable Sub-groups for Income: Implement the necessary logic to fully support sub-groups for the income section.

I am looking forward to collaborate with the community to bring this feature to Actual Budget! Thank you for your time and feedback!

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/actualbudget/actual/pull/5268 **Author:** [@Johnn27](https://github.com/Johnn27) **Created:** 7/2/2025 **Status:** ❌ Closed **Base:** `master` ← **Head:** `feat/sub-categories-johnn27` --- ### 📝 Commits (10+) - [`2a9e296`](https://github.com/actualbudget/actual/commit/2a9e296dfdf5d5b6cc0c695926b5d5c430b31782) feat: sub category groups - [`9d9207c`](https://github.com/actualbudget/actual/commit/9d9207cbb551e773b665006534e8c1c680574de6) chore: release note - [`7618a39`](https://github.com/actualbudget/actual/commit/7618a39e018fe195c03ca94e6353b7da7f9cefab) fix: adding initial child group add budget twice to total - [`d9ec619`](https://github.com/actualbudget/actual/commit/d9ec619b5f250e877d2c8840a0c9133eb9ae63bd) feat: groups for income - [`6a7ef6f`](https://github.com/actualbudget/actual/commit/6a7ef6f29c1cd2753da2d98058077505aaad1d75) chore: rename button to "Add sub-group" - [`9988c6e`](https://github.com/actualbudget/actual/commit/9988c6e805e7b029885d71f0aa1fcd0402d783e2) Merge remote-tracking branch 'origin/master' into feat/sub-categories - [`3c25df1`](https://github.com/actualbudget/actual/commit/3c25df1361580916d620d32174d9b47731450088) Merge remote-tracking branch 'underkoen/feat/sub-categories' into feat/sub-categories-johnn27 - [`0247b9b`](https://github.com/actualbudget/actual/commit/0247b9bbc5a097cf575b4a79a90ceedc712b2e95) Merge branch 'actualbudget:master' into feat/sub-categories-johnn27 - [`7aa6ad3`](https://github.com/actualbudget/actual/commit/7aa6ad3384a1ce563b7d709384e3d3c45fe7e265) Fixing code broken from merge so it is in runnable state - [`7f71f7d`](https://github.com/actualbudget/actual/commit/7f71f7df42f57e7c693bb6f0f9b376311a78084f) Merge branch 'feat/sub-categories-johnn27' of https://github.com/Johnn27/actual into feat/sub-categories-johnn27 ### 📊 Changes **39 files changed** (+2596 additions, -99 deletions) <details> <summary>View changed files</summary> ➕ `docs/hierarchical-categories/README.md` (+91 -0) ➕ `docs/hierarchical-categories/competitive-research.md` (+433 -0) ➕ `docs/hierarchical-categories/implementation-spec.md` (+284 -0) ➕ `docs/hierarchical-categories/mixed-categories-approach.md` (+227 -0) ➕ `docs/hierarchical-categories/risk-analysis.md` (+386 -0) ➕ `docs/hierarchical-categories/user-guide.md` (+75 -0) 📝 `packages/component-library/src/theme.ts` (+1 -0) 📝 `packages/desktop-client/src/components/budget/BudgetCategories.jsx` (+81 -52) 📝 `packages/desktop-client/src/components/budget/BudgetTable.tsx` (+1 -1) 📝 `packages/desktop-client/src/components/budget/ExpenseCategory.tsx` (+3 -0) 📝 `packages/desktop-client/src/components/budget/ExpenseGroup.tsx` (+12 -1) 📝 `packages/desktop-client/src/components/budget/IncomeCategory.tsx` (+3 -0) 📝 `packages/desktop-client/src/components/budget/IncomeGroup.tsx` (+6 -0) 📝 `packages/desktop-client/src/components/budget/IncomeHeader.tsx` (+5 -2) 📝 `packages/desktop-client/src/components/budget/SidebarCategory.tsx` (+6 -1) 📝 `packages/desktop-client/src/components/budget/SidebarGroup.tsx` (+16 -3) 📝 `packages/desktop-client/src/components/budget/envelope/EnvelopeBudgetComponents.tsx` (+3 -2) 📝 `packages/desktop-client/src/components/budget/index.tsx` (+18 -4) 📝 `packages/desktop-client/src/components/settings/Experimental.tsx` (+6 -0) ➕ `packages/desktop-client/src/components/util/BuildCategoryHierarchy.test.ts` (+528 -0) _...and 19 more files_ </details> ### 📄 Description ### ✨ feat: Introduce Hierarchical Category Group (Draft) This pull request introduces the [6th most voted feature](https://github.com/actualbudget/actual/issues/1320) of hierarchical sub-categories, allowing for more granular and organized budgeting. This work is based on the original efforts in [#3772](https://github.com/actualbudget/actual/pull/3772) by @underkoen, which has been updated and adapted to the current codebase. This PR is currently in a __draft stage__. I am actively seeking feedback, suggestions, and guidance from the community and maintainers. I am fully open to changes and requests, and community support for this direction will determine its continuation. ### 🎥 Demo ![chrome_BhTFKz97LW](https://github.com/user-attachments/assets/43f9d88d-68df-45d1-a79e-58441b02128d) ### Key Changes & Implementation Logic The core of this implementation focuses on a robust, client-side approach to hierarchy management to prevent regressions and ensure data consistency. 1. __Client-Side Hierarchy Building:__ Instead of relying on the backend to return a hierarchical structure, the application now always fetches __flat lists__ of categories and category groups. A new, dedicated helper, `buildCategoryHierarchy.ts`, is responsible for transforming this flat data into a nested, hierarchical structure on the front end. This approach is crucial because it allows all existing functionality, such as the category pickers in the Reports tab, to continue working with the flat structure they expect, preventing any breaking changes. 2. __Modular & Testable:__ The `BuildCategoryHierarchy.ts` helper is built with modular, single-responsibility functions, making it highly readable, maintainable, and easy to unit test (which is a key next step!). 3. __UI Integration:__ The `BudgetCategories.jsx` component now uses this new helper to build the category tree, which is then rendered by the `expandGroup` logic. This minimizes changes to the existing component while centralizing the complex data transformation. ### Future Goals & Vision 🚀 If this initial implementation is successful and supported by the community, the end goal is to leverage this new hierarchical data structure for more advanced features, such as: - __Sankey Diagram Report:__ The hierarchical data can be used to build a Sankey diagram report in [#1739](https://github.com/actualbudget/actual/pull/1739) (which I also want to revive). - __Improved Reporting:__ Other reports could also be enhanced to support grouping (e.g. grouped bar charts). ### 📝 TODO & Next Steps If this is endorsed by the maintainers, I will continue with the work below: - [ ] __Unit Tests:__ Add comprehensive unit tests for the new `buildCategoryHierarchy.ts` helper. - [ ] __E2E (Playwright) Tests:__ Create end-to-end tests to cover user interactions with sub-categories. - [ ] __Mobile Display:__ Ensure the hierarchy is displayed correctly and is usable on mobile devices. - [ ] __UI/UX Improvements:__ Refine the grouping order and UI behavior for a polished user experience. - [ ] __Drag-and-Drop:__ Enable drag-and-drop functionality for reordering sub-groups themselves. - [ ] __Enable Sub-groups for Income:__ Implement the necessary logic to fully support sub-groups for the income section. I am looking forward to collaborate with the community to bring this feature to Actual Budget! Thank you for your time and feedback! --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-04-14 21:31:08 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
AI generated
API
bank sync
budgeting
bug
can’t replicate
dependencies
docker
documentation
electron
experimental feature
feature
feedback
goal templates
good first issue
help wanted
importers
maintenance
needs info
needs testing
needs triage
needs votes
openid
payees
pull-request
Mirrored from GitHub Pull Request
 regression
reports
responsive
rules
schedules
server
✨ merged
split transactions
tech debt
tech-support
theme
transaction import
transaction reconciliation
transactions
translations
upstream
user interface
✅ approved
wontfix
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/actual#20214
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?