CTA / Reference / Add (within Collection)

[jamlung-ri]

Spec

KB: ocl-kb/tbv3/02_capabilities/manage-references.md § Add References (Within Collection)

Overview

Build AddReferencesDialog.jsx — a dialog launched from the References tab toolbar that lets a user define and add references to their collection from within the collection context.

Component

src/components/collections/AddReferencesDialog.jsx

Dependencies

• CTA / Reference / Preview #2007 (Reference Preview) — ReferencePreviewPanel is embedded in this dialog
• API: Enhance references/preview/ endpoint for Reference Preview (#2007) #2469 (API: Enhance references/preview/ endpoint) — required for Preview panel to show New vs. Existing grouping and version warnings
• Parent Epic: Author: References #2005 (Author: References)

M42 Scope

• Entry point: References tab → + Add References button (HEAD only, edit access)
• Source / Collection seed field — searchable autocomplete of all sources and collections; seeding populates the expression base path; shows overwrite warning if expression already has content
• Version selector — options: Locked (Currently vX) [if collection has locked version] → Latest (Currently vX) → released version IDs; warning when user changes away from the collection's locked version
• Reference Type selector — Concepts (default) | Mappings; affects seeded expression path
• Expression field — always editable; seeded from source + version + type; user appends IDs, query params, etc.
• Bulk Add — collapsed section; comma-separated concept IDs expanded into N separate extensional expressions using the seeded repo path; requires source/collection to be seeded; warns if expression field would be overwritten
• Include / Exclude toggle — applies to all expressions in submission
• Cascade selector — CascadeSelector component; applies to all expressions
• Preview panel — ReferencePreviewPanel (CTA / Reference / Preview #2007); collapsed by default; fires on expression or batch of Bulk Add IDs; version mismatch and zero-result warnings surfaced here
• Results display — inline success/failure per expression on submit (same pattern as AddToCollectionDialog)

Post-M42 (out of scope)

• Intensional filter builder (Property / Operator / Value UI) — see tbv3-deferred-features.md
• Search-and-select individual concepts from a source — see tbv3-deferred-features.md

Acceptance Criteria

• Dialog opens from + Add References button; button disabled on released versions with tooltip
• Source/Collection seed field populates expression field; overwrite warning shown when expression already has content
• Version selector shows Locked / Latest / version IDs in correct order; "(Currently vX)" label shown on dynamic options
• Warning shown when user changes away from the collection's locked version
• Reference Type selector (Concepts / Mappings) updates the seeded expression path
• Expression field is always directly editable
• Bulk Add requires a seeded source/collection; textarea disabled with tooltip until seeded
• Bulk Add submits N separate expressions; overwrite warning shown when expression field has non-base content
• Include / Exclude applies to all expressions in the submission
• Cascade selector wired and params passed to API call
• Preview panel fires correctly in both expression and Bulk Add modes
• Submit: PUT /:ownerType/:owner/collections/:collection/references/ with correct expressions and cascade params
• Results displayed inline; form locks on completion