GCD-WEB-049 — Navigation Menu Integrity Guard

Price: Free · Version: 1.0.0

Purpose: keep a newly added menu item from replacing an existing item or breaking a horizontal menu when space runs out.

1. Install

Copy navigationMenuIntegrityGuard.ts (TypeScript) or navigationMenuIntegrityGuard.js (JavaScript) into your project. The core helper has no third-party dependency.

2. Use stable IDs

Every existing navigation item needs a stable unique ID. The helper blocks additions that try to reuse an existing ID.

3. Pass real widths

const plan = navigationMenuIntegrityGuard({
  existingItems: [
    { id: "home", width: 64 },
    { id: "services", width: 88 },
    { id: "about", width: 70 }
  ],
  addedItems: [{ id: "contact", width: 82 }],
  availableWidth: 300,
  overflowControlWidth: 64,
  gapPx: 12,
  safetyBufferPx: 8
});

4. Render the strategy

all-visible: render all visibleIds in the main row.
overflow-menu: render visibleIds in the row and overflowIds in an accessible “More” menu.
collapse-menu: use your existing compact/mobile menu button.
invalid: fix duplicate IDs or invalid existing measurements before rendering the update.

5. Preserve the existing menu

Do not replace your entire menu array with the proposed additions. Use plan.mergedItems as the protected merge result. Any blocked additions appear in plan.rejectedAdditions.

Compatibility

Framework-neutral TypeScript/JavaScript core. Suitable for Floot React/TypeScript, React/Next.js, and plain web projects that can measure menu widths and map IDs back to their renderer.

Accessibility

The helper only decides layout. Your “More” or compact menu control still needs keyboard operation, a visible focus state, an accessible name, and correct expanded/collapsed semantics.

Rollback

Remove the helper call and restore the previous menu render path. There are no database, network, persistence, or schema side effects.