A nav item with a counter

1. The nav itemCopy Anchor Link

A nav item (pool nav_items) in etc/adminhtml/di.xml, with the section as parent, your Light route, a fallback_route for when the Light page isn't there, and match so the item is highlighted on your pages:

<item name="account_requests" xsi:type="array">
    <item name="label" xsi:type="string" translate="true">Account requests</item>
    <item name="parent" xsi:type="string">customers</item>
    <item name="route" xsi:type="string">light/accountrequests/index</item>
    <item name="fallback_route" xsi:type="string">requestanaccount/request/index</item>

Nav items that depend on data, such as one item per warehouse, come from a class that implements ItemProviderInterface, registered in the Navigation\Config argument providers (pool nav_providers). Its items take the same keys, plus url: a ready admin URL that Light uses instead of route, and an unsafe one drops the item. Light calls each provider at most once per request, on every page with the nav, so read from a cache or one cheap query. A di.xml item with the same key wins over the provider's, and a provider that throws is logged and its items left out.

The doctor reads files and never calls a provider, so it can't see the keys a provider returns. Name them with #[ProvidesNavItems] on the class when a counter, a to-do or a child item points at one:

#[RequiresModule('MageRex_Support')]
#[ProvidesNavItems('support')]
class SupportItem implements ItemProviderInterface

Leave out keys that only exist at runtime, such as one per warehouse. The doctor reads the attribute from the class and its parents, so a \Proxy carries it, and it skips a provider whose #[RequiresModule] names a module that is off.

2. The counterCopy Anchor Link

A class that implements BadgeSourceInterface returns a Badge or null:

public function getBadgeValue(): ?Badge;

Light lets go of the admin session before it calls your provider, so badges, rows and search answers run in parallel: read the session, never write to it here; a write is lost.

The pilot counts the requests to review. The label is what a screen reader says, in the admin's language:

if ($count <= 0) {
    return null;
}

return new Badge($count, 'attention', (string)($count === 1
    ? __('%1 account request to review', $count)
    : __('%1 account requests to review', $count)));

A badge has no URL: every place that shows the count links to its own target.

3. Register the counterCopy Anchor Link

A BadgePool providers item (pool nav_badge_providers), keyed by a code of your own, names the nav item. rollup also counts on the parent while its section is closed:

<item name="disrex_account_requests" xsi:type="array">
    <item name="item" xsi:type="string">account_requests</item>

The keys are item, provider, resource (default: the nav item's), module, rollup, ttl (seconds a count stays fresh, default 60, at least 10) and sort_order:

Core declares the same list in the catalogue:

<item name="keys" xsi:type="string">item provider resource module rollup ttl sort_order</item>

Several modules can count on one nav item: Light adds the counts, shows the most urgent tone and joins the labels.

4. Drop the count when the work is doneCopy Anchor Link

Light keeps each count in the cache type mrx_light_badges and refreshes it in the background at most once per ttl. When your code changes what you count, drop the cached count at once with BadgeCacheInterface::invalidate(). It works in every area, so a storefront observer, a REST call or a cron job can call it too. The pilot does it after a status change:

$this->badgeCache->invalidate('account_requests');

5. The same count on pins, in the palette and on HomeCopy Anchor Link

• Pins. A pinned app shows the count of its claim's nav_key, or of badge for a declared app (An app, its category and pins).
• Palette. The nav item's "Go to" entry shows the count by itself.
• Home. A to-do with badge shows the count while it is above 0 (Home to-dos, setup steps and widgets).