--- id: CMP-CRM-ENT-008 title: Organization Selector product_area: crm module: entities revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f purpose: Lets staff choose an organization by its record identity while the shared picker resolves its label and search context. reuse: The OrganizationPicker form wrapper and the OrganizationPickerSlot affiliation adapter serve contact forms. Create Organization uses organization selection for hierarchy through its compiled form; the slot is used only while adding an affiliation, not to move an existing affiliation. supports: - CAP-CRM-ENT-002 - CAP-CRM-ENT-003 - CAP-CRM-ENT-009 realises: - CON-CRM-ENT-002 - CON-CRM-ENT-003 props: - name: id type: control identifier required: true default: none meaning: Names the form control or injected affiliation slot. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: value type: identifier text for form wrapper; nullable identifier for slot required: true default: none meaning: Supplies the held organization. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: onChange type: selection handler required: true default: none meaning: The form wrapper reports identifier text; the affiliation slot reports nullable identifier and organization name. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: label type: text on form wrapper required: false default: none meaning: Provides the form field label. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: required type: boolean on form wrapper required: false default: none meaning: Marks the form field required. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: error type: text on form wrapper required: false default: none meaning: Provides validation error wording. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: hint type: rendered help on form wrapper required: false default: none meaning: Provides supporting field guidance. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: placeholder type: text on form wrapper required: false default: Search organizations meaning: Names an empty selection. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: canvas type: form field context required: false default: none meaning: Allows the field shell to integrate with the compiled form. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: className type: presentation classes on form wrapper required: false default: none meaning: Extends form field presentation. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: valueLabel type: text on affiliation slot required: false default: none meaning: Keeps the affiliation’s stored organization name visible when resolution fails. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: invalid type: boolean on affiliation slot required: false default: none meaning: Marks the shared picker invalid from host validation. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx events: - name: form change when: A form-wrapper organization is selected or cleared. payload: Identifier text; empty string means no selection. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - name: affiliation slot change when: A shared-picker organization is selected or cleared. payload: Nullable identifier and option label, or null for the name. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx states: - state: empty experience: The form wrapper offers Search organizations. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - state: loaded experience: Name and secondary context identify matching choices. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - state: held inactive or archived experience: Held-value resolution preserves naming and inactive context without offering all archived records anew. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - state: loading or failed experience: The form wrapper distinguishes loading from load failure and no matching records. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - state: slot unresolved experience: The supplied stored name, or the identifier, keeps the held organization visible. provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx validation: [] accessibility: The form wrapper delegates labels, required markers and errors to FieldShell, and exposes a named Clear action. The shared affiliation picker receives control identity and invalid state from its labeled drawer slot. Popover focus and command semantics are primitive responsibilities; complete keyboard and screen-reader verification is absent. design_system: - field shell - popover - command - button - person summary - tooltip - loading indicator depends_on: [] implementation: CMI-CRM-ENT-008 acceptance: - id: AC-CMP-CRM-ENT-008-01 proved_by: [] statement: Selecting through the form wrapper reports the selected organization identifier; clearing reports an empty string. level: unit provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - id: AC-CMP-CRM-ENT-008-02 proved_by: [] statement: Selecting through the affiliation slot reports identifier and option name together. level: unit provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - id: AC-CMP-CRM-ENT-008-03 proved_by: [] statement: A failed form-wrapper load displays a load-failure message rather than a no-match message. level: unit provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - id: AC-CMP-CRM-ENT-008-04 proved_by: [] statement: The affiliation slot retains the supplied organization name when the source cannot resolve its held identifier. level: unit provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx controls: [] evidence: - react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx narrative_sources: - section: What It Is For provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - section: Where It Is Used provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - section: How It Behaves provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - section: Its Contract provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - section: States provenance: observed source: react-console:components/contact-editor/fields/entity-pickers.tsx; react-console:components/contact-editor/fields/record-picker.tsx; react-console:components/record-pickers/record-picker.tsx; react-console:components/record-pickers/person-option-row.tsx; react-console:components/record-pickers/person-summary.tsx; react-console:lib/record-pickers/sources.ts; react-console:lib/record-pickers/crm-adapter.ts; react-console:lib/record-pickers/source.ts; react-console:lib/record-pickers/inactive.ts; react-console:lib/record-pickers/types.ts; react-console:components/forms/contacts/affiliation-components.tsx - section: Accessibility provenance: unknown source: FND-CRM-ENT-161 - section: Open Design Questions provenance: unknown source: FND-CRM-ENT-161; FND-CRM-ENT-162; FND-CRM-ENT-163 used_by: [CMP-CRM-ENT-004] --- # Organization Selector ## What It Is For Lets staff choose an organization by its record identity while the shared picker resolves its label and search context. The organization-selection responsibility is implemented by OrganizationPicker, a local affiliation slot and the shared organization source. It has no dedicated OrganizationSelector export. The source’s live query adapter and mock list adapter supply the same logical option contract to different consuming controls. ## Where It Is Used The OrganizationPicker form wrapper and the OrganizationPickerSlot affiliation adapter serve contact forms. Create Organization uses organization selection for hierarchy through its compiled form; the slot is used only while adding an affiliation, not to move an existing affiliation. Create Contact and Edit Contact use OrganizationPicker-valued form controls and the affiliation drawer’s organization slot. Create Organization uses the record-field organization variant for hierarchy. The drawer renders this selector only in Add mode. ## How It Behaves OrganizationPicker resolves and locally matches organization options for a compiled form field. The shared affiliation slot instead renders the generic RecordPicker with the workspace’s organization source and a stored-name fallback. The source presents organization-specific context, including record number, parent and location when present. Live reads use the organization query adapter; mock reads use the capped CRM list adapter. The source retains held inactive values while filtering fresh options. No named OrganizationSelector export exists at the pinned commit; this design names the reusable responsibility implemented by those existing pieces. ## Its Contract The wrapper owns neither the saved organization reference nor validation. It resolves the caller’s identifier and emits identifier text when selection changes. The affiliation slot adapts the generic picker’s option into identifier and name because an affiliation draft carries both. Source objects are memoized per workspace and reused across consumers. The older wrapper presents at most forty locally matched options and can request an additional source search when a typed query has no match. The generic picker has its own debounced search and result limit; consumers must not assume those presentations are identical. ## States Empty: The form wrapper offers Search organizations. Loaded: Name and secondary context identify matching choices. Held inactive or archived: Held-value resolution preserves naming and inactive context without offering all archived records anew. Loading or failed: The form wrapper distinguishes loading from load failure and no matching records. Slot unresolved: The supplied stored name, or the identifier, keeps the held organization visible. ## Accessibility The form wrapper delegates labels, required markers and errors to FieldShell, and exposes a named Clear action. The shared affiliation picker receives control identity and invalid state from its labeled drawer slot. Popover focus and command semantics are primitive responsibilities; complete keyboard and screen-reader verification is absent. Accessibility verification is an open obligation recorded in the component accessibility finding. ## Open Design Questions The recorded interaction is observed implementation, with proposed design intent. Component criteria need complete executable bindings and browser accessibility review. Screen owners must wire the registered components into their designs; this slice records usage without changing those screen contracts.