--- id: SCR-CRM-REG-001 title: Regions catalogue route: '/console/{tenantId}/configuration/crm/regions?tab=regions' surface: console product_area: crm module: regions revision: 2 status: draft design_intent: confirmed origin: >- Andrew approved 2026-10-15 (two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner) and 2026-10-12 (an inactive region is a gray Inactive pill, no Status column), cited in services-crm:docs/migrations/crm-regions/README.md; Andrew's row-action rule (2026-10-19), cited in react-console:components/regions/regions-table.tsx implementation_evidence: observed inference: [] source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 purpose: 'Help staff maintain named regional definitions, inspect their rule usage and safely retire or remove them.' supports: - JNY-CRM-REG-001 - JNY-CRM-REG-004 - CAP-CRM-REG-001 - CAP-CRM-REG-002 - CAP-CRM-REG-013 permission: >- The console's CRM settings view alias (crm.regions.read or crm.contact-roles.read); actions as listed, with the service requiring the exact regional key entry_from: - CRM Regions in configuration navigation - The regional page without a tab selection when assignment is disabled - The policy view’s prompt to establish catalogue targets exits_to: - '/console/{tenantId}/configuration/crm/regions?tab=rules' - >- /console/{tenantId}/configuration/crm/regions/assignmentRules (the Add Rule prompt for an existing catalogue without rules) displays: - field: 'Regional names in identifier order, descriptions and a badge for retired definitions.' source: listRegions (every page) - field: A rule-reference count for each definition. source: listRegionAssignmentRules (counted in the browser) - field: Catalogue and coverage totals on the tabs. source: listRegions and listRegionAssignmentRules - field: An explanation that changes are unavailable without management authority. source: the console's settings management alias actions: - label: Add Region (Create Region in the drawer) operation_id: createRegion permission: crm.regions.create (console alias crm.settings.manage) confirm: false - label: Edit (Save Region in the drawer) operation_id: updateRegion permission: crm.regions.update (console alias crm.settings.manage) confirm: false - label: Deactivate operation_id: updateRegion permission: crm.regions.update (console alias crm.settings.manage) confirm: true - label: Activate operation_id: updateRegion permission: crm.regions.update (console alias crm.settings.manage) confirm: false - label: Delete operation_id: deleteRegion permission: crm.regions.delete and the console settings-management alias confirm: true - label: Add Rule operation_id: 'none: opens the rules editor, which loads getRegionAssignmentSettings' permission: crm.regions.update (console alias crm.settings.manage) confirm: false states: - loading - empty - error - read-only - inactive validation: - BR-CAP-CRM-REG-001-01 - BR-CAP-CRM-REG-001-02 - BR-CAP-CRM-REG-001-05 - BR-CAP-CRM-REG-001-10 - BR-CAP-CRM-REG-001-11 - BR-CAP-CRM-REG-001-13 - BR-CAP-CRM-REG-002-01 - BR-CAP-CRM-REG-002-03 - BR-CAP-CRM-REG-002-09 - BR-CAP-CRM-REG-002-10 - BR-CAP-CRM-REG-013-05 patterns: - 'PageLayout with full width, ConfigBreadcrumb and PageHeader' - Line-variant Tabs with URL-selected content - Table rows with a pencil edit button and DropdownMenu ending in Delete - 'EditorDrawer built on Sheet, with unsaved-change protection' - InactiveBadge beside the regional name - ConfirmDialog for retirement and removal - EmptyState with the available create control - Outcome feedback through toasts component: 'components/regions/regions-table.tsx (RegionsTable, RegionDrawer) in components/regions/regions-page.tsx' evidence: - >- react-console at baf6dae3: components/regions/regions-page.tsx, regions-table.tsx, editor-drawer.tsx, use-regions.ts, tabs.ts, paths.ts; components/configuration/area-route.tsx; lib/configuration/regions.ts; lib/authz/backend-aliases.ts; components/regions/__tests__/regions-screen.test.tsx, regions-row-menu.test.tsx, editor-drawers.test.tsx. controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-DAT-001, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003] --- # Regions catalogue ## What the Screen Is For The catalogue tab is where staff maintain the regions used by people, organizations and geographic coverage. With assignment disabled and no selected tab, it opens by default. URL selection preserves a chosen tab through reloads and links. ## What It Shows and Lets People Do The table presents names, descriptions, retirement badges and rule-reference counts. Authorized staff use Add Region or a row’s edit pencil to open the right-hand drawer. Row menus offer retirement or reactivation and place Delete last. Delete also requires the surrounding management gate, in addition to the dedicated delete key. The drawer edits name, description and availability. Creation retains its chosen identifier across retries, and replacement carries back read fields and the version, including hidden integration and lock values. The Add Rule prompt opens the separate policy editor when definitions exist but coverage is empty. ## States and Errors Loading and empty states precede the table; a regional load error offers retry. Read-only users receive an explanation and no management controls. Service refusals appear in drawer feedback or outcome toasts. Retirement and removal require confirmation, and dirty drawers invoke discard protection. ## Patterns It Must Respect The built screen uses the shared page, table, drawer, badge and confirmation components listed in the contract. Management aliases can expose controls that the backend’s exact regional permission subsequently rejects. The service remains the enforcing authority.