docs: organize cross-product documentation
This commit is contained in:
@@ -0,0 +1,193 @@
|
||||
# Quick Access And Product Areas
|
||||
|
||||
## Purpose
|
||||
|
||||
GovOPlaN presents institutional work without requiring ordinary users to
|
||||
understand the installed package graph. Two complementary projections provide
|
||||
that experience:
|
||||
|
||||
- **product areas** group destinations, objects, work and actions by the
|
||||
outcome a person recognizes;
|
||||
- **Quick Access** keeps a small set of task-local tools available without
|
||||
leaving the current page, case, record or Workflow context.
|
||||
|
||||
Technical modules remain the implementation, release and provenance boundary.
|
||||
Product areas and Quick Access are presentation contracts over those owners;
|
||||
they do not copy domain state or bypass authorization.
|
||||
|
||||
Implementation is tracked by Core #283 and #285, GovOPlaN's product-experience
|
||||
umbrella, Views, Policy and `govoplan-quick-access`.
|
||||
|
||||
The repository and product name is `govoplan-quick-access`, with module id
|
||||
`quick_access`. `govoplan-qar` was rejected because the abbreviation hides the
|
||||
purpose in package catalogues, diagnostics, permissions and operations.
|
||||
|
||||
## Implementation Status
|
||||
|
||||
The first production-shaped slice is implemented:
|
||||
|
||||
- Core validates and publishes versioned `product_areas` and
|
||||
`quick_access_tools` manifest contracts;
|
||||
- `govoplan-quick-access` derives its live catalogue from installed modules,
|
||||
persists optimistic-concurrency-protected system, tenant and user profiles,
|
||||
and resolves blocked, forced, ordered and stale preferences;
|
||||
- the shell hosts the optional right rail and one composed drawer with keyboard
|
||||
dismissal, focus return, responsive mobile behavior and full-page fallbacks;
|
||||
- Tasks, Calendar, Mail, Postbox and Files contribute the first owner-rendered
|
||||
tools; Mail and Postbox remain separate sections inside Messages;
|
||||
- immutable View revisions now carry grouped/flat navigation, product-area
|
||||
order and optional labels. Scoped Views therefore configure product
|
||||
presentation for system, tenant, group, user and Workflow contexts;
|
||||
- the expanded left rail groups classified destinations while retaining
|
||||
Dashboard and every authorized unclassified destination under More tools.
|
||||
|
||||
The remaining rollout is classification rather than a missing boundary: other
|
||||
user-facing modules must announce their product areas and future bounded tools,
|
||||
reference journeys need browser accessibility evidence, and richer active-object
|
||||
context should be added only through a separately versioned launch-context
|
||||
contract. Until classification is complete, authorized unclassified routes
|
||||
remain visible rather than disappearing.
|
||||
|
||||
## Quick Access Boundary
|
||||
|
||||
Core owns a versioned contribution contract. Feature modules may register a
|
||||
tool when they have a useful bounded surface. They do not import Quick Access.
|
||||
`govoplan-quick-access` owns configuration, effective resolution, ordering,
|
||||
the right-side rail and its drawer. Views may narrow tools for the current
|
||||
task. Policy may constrain availability and customization. Access and each
|
||||
owner's backend remain authoritative.
|
||||
|
||||
The initial categories are:
|
||||
|
||||
| Category | Typical contributions |
|
||||
| --- | --- |
|
||||
| Work | Explicit Tasks, Workflow handoffs, approvals, deadlines and exceptions |
|
||||
| Calendar | Today/upcoming agenda, event creation and scheduling launch |
|
||||
| Messages | Mail, function-bound Postbox messages and future governed chat providers |
|
||||
| Files | Contextual/recent files, attachment selection and upload |
|
||||
|
||||
Messages is one shell category but not one data model. Mail, Postbox and future
|
||||
chat providers retain their channel semantics, custody, policy, audit and
|
||||
delivery behavior. The drawer identifies the channel where that distinction
|
||||
matters.
|
||||
|
||||
## Contribution Contract
|
||||
|
||||
A Quick Access contribution declares:
|
||||
|
||||
- a stable id, category and human label;
|
||||
- icon, order and optional badge/summary provider;
|
||||
- required permissions and optional dependencies;
|
||||
- accepted context references and produced return references;
|
||||
- an owner-rendered bounded WebUI surface and full-page fallback route;
|
||||
- View surface, help context and availability explanation;
|
||||
- whether the contribution supports preview, create, select or resume.
|
||||
|
||||
The shell passes only bounded references: tenant, acting context, temporal
|
||||
read context, active task/Workflow, current institutional object, selected
|
||||
resources and a safe return location. The owner reauthorizes every read and
|
||||
effect. Credentials, protected content and permission decisions are never
|
||||
embedded in launch context.
|
||||
|
||||
## Effective Configuration
|
||||
|
||||
The effective rail is resolved from:
|
||||
|
||||
1. installed and enabled modules and their registered contributions;
|
||||
2. system availability, forced entries and ordering defaults;
|
||||
3. tenant availability, forced entries and ordering defaults;
|
||||
4. group and user View/Policy ceilings where configured;
|
||||
5. the user's enabled categories, entries and ordering;
|
||||
6. the active View and optional Workflow-step narrowing overlay;
|
||||
7. current authorization and contribution availability.
|
||||
|
||||
Lower scopes may narrow or reorder allowed entries but cannot enable a tool
|
||||
blocked above them. A forced entry cannot be removed below its source. User
|
||||
configuration stores stable contribution ids; unavailable or retired ids are
|
||||
retained as explained stale preferences without rendering broken controls.
|
||||
|
||||
Configuration screens derive their available choices from the live registry.
|
||||
Installing or enabling a contributing module adds its permitted choices;
|
||||
disabling it removes the runtime tool while preserving harmless preferences.
|
||||
If Quick Access is absent, contributors behave exactly as before.
|
||||
|
||||
## Interaction Model
|
||||
|
||||
Desktop uses a narrow right-side rail with at most four initial category
|
||||
buttons and an overflow when an administrator or user adds more categories.
|
||||
Selecting a category opens one fixed, owner-neutral drawer. Contributions are
|
||||
shown inside that drawer as tabs, sections or commands according to the
|
||||
category contract. The default drawer overlays content so DataGrid and fixed
|
||||
workspace layouts do not resize unexpectedly; a later explicit pinned mode may
|
||||
reserve layout width on sufficiently wide screens.
|
||||
|
||||
The drawer preserves host-page state, has a deterministic focus return, closes
|
||||
with Escape, supports keyboard traversal, and provides an explicit full-page
|
||||
open action. Mobile and narrow layouts use the same category/configuration
|
||||
semantics in a bottom sheet or compact menu.
|
||||
|
||||
## Product Areas
|
||||
|
||||
Product areas are stable configurable identities, not repositories. The
|
||||
recommended baseline is:
|
||||
|
||||
- Work;
|
||||
- Services and Cases;
|
||||
- Records and Documents;
|
||||
- Communication;
|
||||
- Meetings and Decisions;
|
||||
- Data and Assurance;
|
||||
- People and Responsibility.
|
||||
|
||||
Modules contribute routes, objects, actions, widgets, work sources and help to
|
||||
one or more areas. Product packages and administrators may define sensible
|
||||
system and tenant defaults. Views select, order, rename or narrow allowed
|
||||
areas, and users may personalize them within Policy ceilings. An empty area is
|
||||
omitted. An area with one destination may open it directly. A multi-destination
|
||||
area provides a useful work/recent/action surface rather than another menu.
|
||||
|
||||
Familiar product nouns such as Calendar, Mail or Files may remain directly
|
||||
pinned. The objective is not to hide every module name; it is to prevent
|
||||
repository topology from determining a person's workflow.
|
||||
|
||||
## Full Access And Provenance
|
||||
|
||||
The existing permission-derived module rail remains available as **All
|
||||
available tools** for power users and deliberate escape from a focused View.
|
||||
It contains only currently authorized destinations. Technical module,
|
||||
capability, provider and package provenance remains visible in administration,
|
||||
diagnostics, evidence and expandable details.
|
||||
|
||||
Search, deep links and help distinguish three states:
|
||||
|
||||
- available in the active View;
|
||||
- authorized but outside the active View, with a temporary escape or View
|
||||
switch;
|
||||
- unavailable because of authorization, Policy, configuration or a missing
|
||||
capability, with an actionable explanation.
|
||||
|
||||
## Delivery Order
|
||||
|
||||
1. Define Core product-area and Quick Access contracts and validation.
|
||||
2. Implement `govoplan-quick-access` configuration, effective resolution and
|
||||
shell capability.
|
||||
3. Contribute Work, Calendar, Messages and Files bounded surfaces.
|
||||
4. Add configurable product-area defaults through Views and product packages.
|
||||
5. Migrate navigation, breadcrumbs, search, errors, documentation, dashboard
|
||||
and administration toward product terminology.
|
||||
6. Prove keyboard, focus, responsive, optional-module and reference-journey
|
||||
behavior before making it the ordinary-user default.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A user can configure allowed Quick Access categories and ordering without
|
||||
gaining authority.
|
||||
- System and tenant administrators can make entries available, forced or
|
||||
unavailable with provenance.
|
||||
- Mail, Postbox and another future channel can share Messages presentation
|
||||
while retaining independent state and channel semantics.
|
||||
- A reference journey can use a bounded tool and return without losing host
|
||||
state or Workflow context.
|
||||
- Product areas remain useful under sparse and rich permission sets and under
|
||||
optional-module permutations.
|
||||
- All available tools and technical provenance remain deliberately reachable.
|
||||
Reference in New Issue
Block a user