# Menu Metadata Guide

## Purpose

This guide explains how to add routes and navigation entries using central route metadata in `routes.php`.

## Single Source Of Truth

`routes.php` is now the canonical registry for page identity metadata.
Each route entry can define:

1. `file`: PHP content fragment file name.
2. `label`: Menu and navigation label.
3. `title`: Browser/page title label.
4. `admin_only`: Optional boolean access hint for admin-only pages.

Example:

```php
'adminToolsAudits' => [
    'file' => 'adminToolsAudits.php',
    'label' => 'Audits',
    'title' => 'Audits',
    'admin_only' => true,
],
```

## How To Add A New Menu Entry

1. Create the page file (for example `myNewPage.php`).
2. Add route metadata to `routes.php`.
3. Add a navigation placement in `sidebar.php` by calling:
   - `navLink('myNewPage', routeLabel('myNewPage', 'Fallback Label'), 'fa-icon-class')`
4. Optionally add topbar shortcuts in `header.php` using `data-page` and `data-label`.
5. Run checks:
   - `php -l templ.php sidebar.php header.php routes.php myNewPage.php`
6. Open the page and verify:
   - Full load: `templ.php?page=myNewPage`
   - AJAX navigation from menu

## CLI Tooling

Use `tools/route_metadata_tools.php` for validation and CRUD-friendly updates.

Validation:

1. `php tools/route_metadata_tools.php validate`
2. `php tools/route_metadata_tools.php validate --json`

List:

1. `php tools/route_metadata_tools.php list`

Create:

1. `php tools/route_metadata_tools.php add --key=myNewPage --file=myNewPage.php --label="My New Page" --title="My New Page"`

Update:

1. `php tools/route_metadata_tools.php update --key=myNewPage --label="My Updated Label" --title="My Updated Title"`

Delete:

1. `php tools/route_metadata_tools.php delete --key=myNewPage`

Scaffold snippets for sidebar/header/footer references:

1. `php tools/route_metadata_tools.php scaffold --key=myNewPage`

## Why Sidebar Still Needs Editing

`routes.php` stores route metadata, but `sidebar.php` still controls information architecture (section placement, submenu structure, badges).
This is intentional so IA decisions stay explicit.

## Menu Nomenclature And Nesting

Use these terms consistently when discussing or editing navigation:

1. Parent item: a collapsible menu node that contains children.
2. Child item: an item directly under a parent.
3. Leaf item: a child with no submenu.
4. Siblings: items at the same level under one parent.
5. Ancestor/descendant: relationships across multiple levels.

Current project rule of thumb:

1. Keep production navigation shallow unless a real use case requires depth.
2. Use deep trees only for explicit demos (for example, the Nested Menu Demo section in `sidebar.php`).
3. In demo trees, keep labels predictable and level-specific.

## Do We Need A Form To Edit Metadata?

Not yet.

1. Current scale is small and code review is preferred for navigation changes.
2. A form adds validation, auth, and migration complexity.
3. If non-developers need to manage menus later, build a controlled admin editor after metadata schema is stable.

## Future Upgrade Path (Optional)

If menu management needs to be non-technical:

1. Move route metadata to a validated JSON/YAML source.
2. Add a schema validator and CI check.
3. Add an admin-only editor UI with role checks and audit logging.