govoplan-core/docs/CONTEXTUAL_HELP_CONTRACT.md

Contextual Help Contract

GovOPlaN exposes context-sensitive help through F1 and the titlebar help control. The shell resolves a stable help identity from the focused control, its containing surface, and the current route. The Docs module then projects the best visible user or administrator topic for that identity.

Resolution Order

The WebUI resolves help in this order:

1. an explicit helpContextId or data-help-context-id on the focused item
2. the focused shared control's interfaceId, helpTopicId, and label key
3. a containing dialog, card, administration section, or page surface
4. the current registered route, including dynamic module routes
5. a stable route-derived fallback when no explicit identity is available

Focused field and action contexts retain the page context as fallback_context. This lets Docs show a field-specific topic when one exists and otherwise open the owning page or module documentation instead of a generic help page.

Documentation Lookup

Static DocumentationTopic contributions announce exact contexts through metadata.help_contexts. Core publishes that catalogue with the enabled module manifest, allowing the shell to link directly to an exact topic when possible. Docs still performs the authoritative audience, permission, configured-state, and documentation-type filtering.

Core also maps explicit route, navigation, settings, and View surface IDs to the module's static user or administrator documentation baseline. This makes a page association complete by default and gives every derived field/action context a useful fallback. Exact metadata.help_contexts remain the preferred authoring mechanism for consequential or unfamiliar controls.

When there is no exact topic, Docs resolves the page fallback and then the first visible topic owned by the module. If Docs is unavailable, the shell opens the hosted documentation with the same context parameters.

Authoring Controls

Core shared controls expose stable help metadata. Prefer these props rather than adding custom F1 listeners:

• interfaceId identifies a durable UI surface or action.
• helpContextId identifies a documentation context when it differs from the interface identity.
• helpTopicId links directly to a module-owned documentation topic.
• translated label keys provide deterministic field identities for ordinary FormField, ToggleSwitch, search, date/time, email, button, dialog, and card controls.

Module routes, public routes, settings sections, and administration sections may also declare helpContextId and helpTopicId. Each module must keep a static user/admin documentation baseline and should list its important route, workflow, setting, permission, and limitation identities in metadata.help_contexts.

Boundary

Help identities describe presentation context; they are not authorization claims. Opening help never bypasses route or documentation permissions. Docs owns documentation projection, feature modules own their content, and Core owns focus capture, context resolution, and fallback routing.