# Move Category

<!-- User story defining a specific requirement within a business flow.
The name of the story should start with the actor followed by `--` and the story name.
 -->

<!-- This section should contain the following subsections in order: -->
<!-- 1. ## User Story (required) -->
<!-- 2. ## Story Diagram (required) -->
<!-- 3. ## Scenario Patterns (required) -->
<!-- 4. ## Test Cases (required) -->
<!-- 5. ## Screens (required) -->
<!-- 6. ## Resolvers (required) -->

## User Story

As a product manager, I want to reparent a category to a different parent or to the root level, so that I can reorganise the category hierarchy without losing category data.

## Story Diagram

<!-- Mermaid flowchart showing user interactions with screens.
Focus on actors, UI screens, and business outcomes.
Avoid technical details (APIs, databases, endpoints).
 -->

<!-- Code block requirements: -->
<!-- Minimum 1 mermaid code blocks required -->

```mermaid
flowchart TD
    A([Product Manager]) --> B[Category Detail Screen]
    B --> C[Move Category Form]
    C --> D{Submit with newParentId}
    D --> E{newParentId is null?}
    E -- Yes --> F[Category moved to root]
    E -- No --> G{Circular reference?}
    G -- No --> H{Max depth exceeded?}
    H -- No --> I[Category moved to new parent]
    H -- Yes --> J[Error: Maximum hierarchy depth exceeded]
    G -- Yes --> K[Error: Cannot set parent to a descendant]
    F --> B
    I --> B
```

## Scenario Patterns

- Move to root: providing null as newParentId detaches the category from its parent and places it at the root level
- Move to new parent: providing a valid newParentId that is not a descendant of the category places the category under the new parent
- Circular reference error: setting newParentId to the category itself or any of its descendants is rejected
- Max depth error: moving the category would exceed the allowed hierarchy depth and is rejected

## Test Cases

- Given a valid category and newParentId set to null, the category is moved to root level
- Given a valid category and a valid non-descendant newParentId, the category is reparented successfully
- Given newParentId equal to the category's own ID, the move fails with a circular reference error
- Given newParentId equal to a descendant of the category, the move fails with a circular reference error
- Given a move that would exceed the maximum allowed depth, the move fails with a max depth error

## Screens

- [category-detail](../../../screen/category-detail.md)

## Resolvers

<!-- Link to resolver docs that implement this story's backend operations.
Write "None" if this story does not require any resolvers.
 -->

- [moveCategory](../../../resolver/moveCategory.md)
