# Menu Builder / Navigation Manager Specification

## Goal

Provide a WordPress-like admin menu builder where admins can configure site navigation through a dropdown/tree UI.

## Requirements

Admin can:
- create menu locations
- select/edit a menu
- add menu items
- drag/drop reorder
- create nested items
- edit labels
- choose internal links
- enter custom URLs
- choose target
- enable/disable item
- optionally add CSS class/icon if current design needs it

## Recommended model

If no existing menu system exists:

`menus`
- id
- name
- location/key
- is_active
- timestamps

`menu_items`
- id
- menu_id
- parent_id nullable
- title
- type
- target_id nullable
- url nullable
- sort_order
- target_blank boolean
- is_active boolean
- metadata/json nullable
- timestamps

`type` examples:
- category
- product
- blog_category
- blog_post
- page
- custom_url

Do not create separate columns for every entity type when polymorphic/reference logic can be kept clean.

## Frontend rendering

Render menus from a reusable Blade component, e.g.:
`<x-navigation-menu location="header" />`

The renderer must:
- preserve hierarchy
- output accessible navigation
- support keyboard navigation
- support mobile menu if the current frontend has one
- avoid N+1 queries
- cache safely

## Admin UX

Menu manager:
1. choose location/menu
2. left panel = available items
3. right panel = current menu tree
4. drag/drop
5. save
6. publish/apply

Prevent malformed trees.

Validate:
- parent item belongs to same menu
- no cycles
- no orphan items
- valid target entity exists for entity-based items

## SEO/accessibility

Use real `<a href>` links.

Do not hide primary navigation behind JS-only interactions.

Use descriptive labels.

Avoid massive repeated keyword-rich navigation.

## Caching

Menu rendering may be cached, but cache must be invalidated when:
- menu saved
- menu item added/updated/deleted
- target entity URL changes if cache stores resolved URLs

## Backward compatibility

Inspect existing hardcoded header/footer menus.

If they exist:
- migrate their meaningful items
- replace rendering incrementally
- keep fallback menu if no configured menu exists

## Tests

- create menu
- add item
- reorder
- nest
- prevent cycle
- disable item
- entity link resolves
- deleted target handled safely
- frontend renders correct order
- cache invalidation