73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# 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.
|
|
- `helpModuleId` identifies the documentation-owning module when a shared
|
|
control is embedded in another module's page.
|
|
- `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.
|
|
- `TableActionGroup` action definitions carry the same identities so focused
|
|
row actions can resolve consequence-specific help.
|
|
- `PageLayout` owns the page help scope and documentation identity for ordinary
|
|
headed pages; specialized full-canvas workspaces reuse `PageHeader` while
|
|
keeping their route-level help identity on the owning workspace.
|
|
|
|
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.
|