Implement a Cocina description editor

This implementation was written by Claude Code using design artifacts in
https://github.com/sul-dlss-labs/cocina-editor-design/

What follows is a summary of the implementation written by Claude after
implementing the design and several rounds of edits that are preserved
in the chat transcript alongside the design documents.

---

This document records what was built, key decisions made during implementation, and
where the final result diverged from the original `design.md`.

All three phases from the design plan were completed:

- **Titles** — simple value + type, and structured titles (main title, subtitle, part
  number, part name) each with an editable type select per part
- **Notes** — value + type dropdown
- **Language** — code + label
- **Contributors** — simple name or structured name + life dates, type, primary toggle,
  role field
- **Subjects** — flat `{value, type, source}` and flat LCSH compound headings
  (`structuredValue` with editable part types)
- **Events** — date, event type, publisher, place
- **Form** — fully implemented (not just extent as originally scoped); value + type +
  source
- **Access** — physical location and access contact
- **Related resources** — title, relationship type, URL

The route is `GET/PATCH /objects/:object_druid/description` (nested under the existing
`:objects` resource using its `param: :druid` convention, not `/items` as sketched in
the design).

The design's core approach (curated form for common shapes, raw JSON textarea escape
hatch for everything else) proved sound and was applied consistently across all six field
types that have polymorphic shapes. The boundary condition — "flat `structuredValue` →
curated, nested `structuredValue` → JSON" — held up against all 11 sample objects.

The JSON escape hatch was further improved with:
- **Server-side pretty-printing** via `JSON.pretty_generate` so complex JSON is readable
  at a glance
- **Info callouts** explaining specifically why a given item fell back to JSON (e.g.
  "This event contains a structured or parallel date range and must be edited as JSON"),
  computed from the same conditions that triggered the fallback
- **Auto-formatting** on blur via a `json_formatter` Stimulus controller that re-indents
  valid JSON and flags invalid JSON with Bootstrap's `is-invalid` style
- **"Show JSON" toggle** on curated items so editors can inspect the underlying data
  without switching to raw editing

For fields where the form only exposes a subset of properties (events, contributors,
structured titles), the full original JSON is stored in a `_original` hidden field and
used as the base when rebuilding the object on save. This preserves fields not yet
surfaced by the editor (MARC country codes, date encoding attributes, role URIs, etc.)
without the editor needing to know about them.

Rather than relying on Stimulus to serialize the form to JSON (as the design sketched),
the controller rebuilds each section from standard Rails form params via a set of
`build_title`, `build_contributor`, `build_subject`, `build_event`, `build_form`, and
`build_related_resource` methods. These merge submitted fields back into the existing
description, preserving any fields not exposed by the editor.

In real SDR data, the event `type` is often stored on `date[0].type` rather than on the
event itself. The display resolved this with:

```ruby
event_type = event[:type].presence || event.dig(:date, 0, :type)
```

This matches the logic in the `cocina_display` gem's `event.rb`.

Publication events frequently carry two location entries — a human-readable place name
and a MARC country code:

```json
"location": [{"value": "New York"}, {"code": "nyu"}]
```

The original implementation replaced all locations with a single entry. The fix
identifies the value-bearing entry by index and updates only that one, leaving the code
entry untouched.

Publisher names in events follow the pattern:
```json
{"contributor": [{"name": [{"value": "Munn & Co."}], "type": "organization",
                  "role": [{"value": "publisher", ...}]}]}
```
This is common enough that it was promoted to a curated `publisher` field in the event
form rather than left to the JSON escape hatch.

The design anticipated raw JSON for structured values. In practice, all `structuredValue`
arrays in the sample data are flat (depth 1), so a curated form was built for both:

- **Titles**: each `structuredValue` part rendered as a value input + type select
  (main title, subtitle, part number, part name, nonsorting characters), with a
  separate title-level type select (alternative, uniform, translated, etc.)
- **Subjects**: flat LCSH compound headings rendered as a list of value + type select
  rows, preserving the full original via `_struct_original`

Deeply nested `structuredValue` (depth > 1) still falls through to the JSON textarea.

| Design | Actual |
|---|---|
| Field-level error injection via Turbo Streams | Flash warnings at page level; Turbo Stream error injection deferred |
| ETag / lock field for concurrent edit protection | Not implemented; deferred |
| Stimulus serializes form to JSON on submit | Standard Rails form params; controller rebuilds description |
| `form` scoped to extent only | Full form field implemented (all types) |
| Route `/items/:druid/description` | `/objects/:object_druid/description` (matches existing resource) |
| Inline error paths from `Cocina::Models::ValidationError` | `CocinaSupport.validate` returns a `Dry::Monads::Failure` string; shown as flash |

- **Controller**: `app/controllers/descriptions_controller.rb`
- **Edit view**: `app/views/descriptions/edit.html.erb`
- **Field partials**: `app/views/descriptions/_*_fields.html.erb`
- **JSON toggle partial**: `app/views/descriptions/_json_toggle.html.erb`
- **Stimulus controllers**: `description_editor_controller.js`, `json_formatter_controller.js`
- **Request spec**: `spec/requests/descriptions_spec.rb`
- **Route**: `config/routes.rb` — `resource :description` nested under `resources :objects`
- **Policy**: `app/policies/object_policy.rb` — `edit_description?`

Author: edsu

.rubocop.yml

@@ -38,7 +38,7 @@ Metrics/BlockLength:
     - 'config/routes.rb'
 
 Metrics/ClassLength:
-  Max: 150 # default 100
+  Max: 200 # default 100
 
 Metrics/MethodLength:
   CountAsOne:

app/controllers/descriptions_controller.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Controller for editing the descriptive metadata of an object.
+class DescriptionsController < ApplicationController
+  before_action :load_cocina_object
+
+  FIELD_RESULT_KEY = {
+    'title' => :title, 'note' => :note, 'language' => :language,
+    'contributor' => :contributor, 'subject' => :subject, 'form' => :form,
+    'event' => :event, 'related_resource' => :relatedResource
+  }.freeze
+
+  FIELD_MODEL_CLASS = {
+    'title' => Cocina::Models::Title,
+    'note' => Cocina::Models::DescriptiveValue,
+    'language' => Cocina::Models::Language,
+    'contributor' => Cocina::Models::Contributor,
+    'subject' => Cocina::Models::DescriptiveValue,
+    'form' => Cocina::Models::DescriptiveValue,
+    'event' => Cocina::Models::Event,
+    'related_resource' => Cocina::Models::RelatedResource
+  }.freeze
+
+  def edit
+    authorize! @cocina_object, with: ObjectPolicy, to: :edit_description?
+    open_version_if_needed!
+  rescue Sdr::Repository::Error
+    # If pre-opening fails, save will attempt it again
+  end
+
+  # rubocop:disable Metrics/AbcSize
+  def field_json
+    authorize! @cocina_object, with: ObjectPolicy, to: :edit_description?
+
+    result_key = FIELD_RESULT_KEY[params.require(:field_type)]
+    return head :bad_request unless result_key
+
+    built = DescriptionBuilder.new(existing_description: {}).build(description_params)
+    item = built[result_key]&.first
+    return head(:unprocessable_content) unless item
+
+    render json: FIELD_MODEL_CLASS[params[:field_type]].new(item).to_h
+  rescue ActionController::ParameterMissing, JSON::ParserError,
+         Cocina::Models::ValidationError, Dry::Struct::Error
+    head :unprocessable_content
+  end
+  # rubocop:enable Metrics/AbcSize
+
+  def render_field
+    authorize! @cocina_object, with: ObjectPolicy, to: :edit_description?
+
+    data = JSON.parse(params.require(:json)).deep_symbolize_keys
+    result = field_partial_config(params.require(:field_type), data)
+    return head :bad_request unless result
+
+    render partial: result[:partial], locals: result[:locals]
+  rescue JSON::ParserError, Cocina::Models::ValidationError, Dry::Struct::Error
+    head :unprocessable_content
+  end
+
+  def update
+    authorize! @cocina_object, with: ObjectPolicy, to: :edit_description?
+
+    new_description = build_description
+    validate_result = CocinaSupport.validate(@cocina_object, description: new_description)
+
+    if validate_result.failure?
+      flash.now[:warning] = validate_result.failure
+      render :edit, status: :unprocessable_content
+      return
+    end
+
+    save_description!(new_description)
+  rescue Sdr::Repository::Error => e
+    flash.now[:warning] = e.message
+    render :edit, status: :unprocessable_content
+  end
+
+  private
+
+  def load_cocina_object
+    @cocina_object = Sdr::Repository.find(druid: params.expect(:object_druid))
+  rescue Sdr::Repository::NotFoundResponse
+    redirect_to root_path, flash: { warning: 'Object not found.' }
+  end
+
+  def open_version_if_needed!
+    return if Sdr::VersionService.open?(druid: @cocina_object.externalIdentifier)
+
+    Sdr::VersionService.open(druid: @cocina_object.externalIdentifier,
+                             description: 'Descriptive metadata edited via web form',
+                             opening_user_name: current_user.sunetid)
+  rescue Dor::Services::Client::Error => e
+    raise Sdr::Repository::Error, "Opening version failed: #{e.message}"
+  end
+
+  def close_version!
+    druid = @cocina_object.externalIdentifier
+    Sdr::VersionService.close(druid:) if Sdr::VersionService.closeable?(druid:)
+  rescue Dor::Services::Client::Error => e
+    raise Sdr::Repository::Error, "Closing version failed: #{e.message}"
+  end
+
+  def save_description!(new_description)
+    open_version_if_needed!
+    updated_object = @cocina_object.new(description: new_description)
+    Sdr::Repository.update(cocina_object: updated_object,
+                           user_name: current_user.sunetid,
+                           description: 'Descriptive metadata edited via web form')
+    close_version!
+    redirect_to object_path(druid: @cocina_object.externalIdentifier), flash: { success: 'Description updated.' }
+  end
+
+  # rubocop:disable Metrics/CyclomaticComplexity
+  def field_partial_config(field_type, data)
+    case field_type
+    when 'title'       then { partial: 'descriptions/title_fields',
+                              locals: { title: Cocina::Models::Title.new(data) } }
+    when 'note'        then { partial: 'descriptions/note_fields',
+                              locals: { note: Cocina::Models::DescriptiveValue.new(data) } }
+    when 'language'    then { partial: 'descriptions/language_fields',
+                              locals: { language: Cocina::Models::Language.new(data) } }
+    when 'contributor' then { partial: 'descriptions/contributor_fields', locals: { contributor: data } }
+    when 'subject'     then { partial: 'descriptions/subject_fields',     locals: { subject: data } }
+    when 'form'        then { partial: 'descriptions/form_fields',         locals: { form: data } }
+    when 'event'       then { partial: 'descriptions/event_fields',        locals: { event: data } }
+    when 'related_resource' then { partial: 'descriptions/related_resource_fields',
+                                   locals: { related_resource: data } }
+    end
+  end
+  # rubocop:enable Metrics/CyclomaticComplexity
+
+  def build_description
+    DescriptionBuilder.new(existing_description: @cocina_object.description.to_h)
+                      .build(description_params)
+  end
+
+  # rubocop:disable Rails/StrongParametersExpect
+  def description_params
+    params.require(:description).permit(
+      title: [:value, :type, :_raw_json, :_original, { struct_parts: %i[value type] }],
+      note: %i[value type _raw_json],
+      language: %i[code value _raw_json],
+      contributor: %i[_raw_json _original name_value life_dates type primary role_value],
+      subject: [:_raw_json, :value, :type, :source_code, :_struct_original, { struct_parts: %i[value type] }],
+      form: %i[_raw_json value type source_code],
+      event: %i[_raw_json _original date_value date_start_value date_end_value type place_value publisher_value],
+      related_resource: %i[_raw_json title_value type url],
+      access: { physical_location: %i[value type], access_contact: %i[value type] }
+    ).to_h.deep_symbolize_keys
+  end
+  # rubocop:enable Rails/StrongParametersExpect
+end

app/javascript/controllers/cocina_model_show_controller.js

@@ -61,7 +61,8 @@ export default class extends Controller {
       this.frameReloadTimeouts = []
 
       // Reload frames one at a time to spread out requests and reduce bursts.
-      frames.forEach((frame, index) => {
+      // Skip frames containing forms — reloading would discard the user's unsaved input.
+      frames.filter(frame => !frame.querySelector('form')).forEach((frame, index) => {
         const timeoutId = setTimeout(() => {
           if (document.visibilityState === 'visible') frame.reload()
         }, index * this.staggerValue)

app/javascript/controllers/description_editor_controller.js

@@ -0,0 +1,16 @@
+import { Controller } from '@hotwired/stimulus'
+
+// Manages the dynamic addition and removal of array items in the description editor.
+export default class extends Controller {
+  addItem (event) {
+    event.preventDefault()
+    const list = document.getElementById(event.currentTarget.dataset.listId)
+    const template = document.getElementById(event.currentTarget.dataset.templateId)
+    list.appendChild(template.content.cloneNode(true))
+  }
+
+  removeItem (event) {
+    event.preventDefault()
+    event.currentTarget.closest('[data-item]').remove()
+  }
+}

app/javascript/controllers/description_field_controller.js

@@ -0,0 +1,51 @@
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+  #debounceTimer = null
+  #handleChange = (event) => {
+    // Ignore hidden inputs and the JSON textarea itself (that syncs the other direction)
+    if (event.target.type === 'hidden') return
+    if (event.target.closest('[data-controller~="json-formatter"]')) return
+
+    clearTimeout(this.#debounceTimer)
+    this.#debounceTimer = setTimeout(() => this.#sendUpdate(), 400)
+  }
+
+  connect () {
+    this.element.addEventListener('input', this.#handleChange)
+    this.element.addEventListener('change', this.#handleChange)
+  }
+
+  disconnect () {
+    this.element.removeEventListener('input', this.#handleChange)
+    this.element.removeEventListener('change', this.#handleChange)
+    clearTimeout(this.#debounceTimer)
+  }
+
+  #sendUpdate () {
+    const fieldType = this.element.dataset.fieldType
+    const urlContainer = this.element.closest('[data-field-json-url]')
+    if (!fieldType || !urlContainer) return
+
+    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content
+    const params = new URLSearchParams({ field_type: fieldType })
+    const selector = 'input:not([disabled]), select, textarea:not([disabled]):not([data-controller~="json-formatter"])'
+    this.element.querySelectorAll(selector).forEach(el => {
+      if (el.name) params.append(el.name, el.value)
+    })
+
+    fetch(urlContainer.dataset.fieldJsonUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'X-CSRF-Token': csrfToken },
+      body: params.toString()
+    })
+      .then(response => response.ok ? response.json() : null)
+      .then(json => {
+        if (!json) return
+        const textarea = this.element.querySelector('[data-controller~="json-formatter"]')
+        if (!textarea) return
+        textarea.value = JSON.stringify(json, null, 2)
+      })
+      .catch(() => {})
+  }
+}

app/javascript/controllers/json_formatter_controller.js

@@ -0,0 +1,88 @@
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+  #collapse = null
+  #onShow = () => { this.element.disabled = false }
+  #onShown = () => { this.resize() }
+  #onHide = () => { this.element.disabled = true }
+
+  connect () {
+    const collapse = this.element.closest('.collapse')
+    if (collapse) {
+      this.element.disabled = !collapse.classList.contains('show')
+      collapse.addEventListener('show.bs.collapse', this.#onShow)
+      collapse.addEventListener('shown.bs.collapse', this.#onShown)
+      collapse.addEventListener('hide.bs.collapse', this.#onHide)
+      this.#collapse = collapse
+    }
+    this.resize()
+  }
+
+  disconnect () {
+    if (this.#collapse) {
+      this.#collapse.removeEventListener('show.bs.collapse', this.#onShow)
+      this.#collapse.removeEventListener('shown.bs.collapse', this.#onShown)
+      this.#collapse.removeEventListener('hide.bs.collapse', this.#onHide)
+    }
+  }
+
+  resize () {
+    this.element.style.height = 'auto'
+    this.element.style.height = `${Math.max(this.element.scrollHeight, 160)}px`
+  }
+
+  format () {
+    try {
+      const parsed = JSON.parse(this.element.value)
+      this.element.value = JSON.stringify(parsed, null, 2)
+      this.element.classList.remove('is-invalid')
+      this.resize()
+      this.syncToForm()
+    } catch {
+      this.element.classList.add('is-invalid')
+    }
+  }
+
+  syncToForm () {
+    // Only sync json_toggle textareas (inside .collapse), not the "must edit as JSON" fallback ones
+    const collapse = this.element.closest('.collapse')
+    if (!collapse) return
+
+    const dataItem = this.element.closest('[data-item]')
+    if (!dataItem) return
+
+    const fieldType = dataItem.dataset.fieldType
+    if (!fieldType) return
+
+    const urlContainer = this.element.closest('[data-render-field-url]')
+    if (!urlContainer) return
+
+    const url = urlContainer.dataset.renderFieldUrl
+    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content
+
+    fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
+      body: JSON.stringify({ field_type: fieldType, json: this.element.value })
+    })
+      .then(response => response.ok ? response.text() : null)
+      .then(html => {
+        if (!html) return
+        const temp = document.createElement('div')
+        temp.innerHTML = html
+        const newItem = temp.firstElementChild
+        if (!newItem) return
+
+        // Re-open the collapse so the user can keep editing
+        const newCollapse = newItem.querySelector('.collapse')
+        if (newCollapse) {
+          newCollapse.classList.add('show')
+          const toggleBtn = newItem.querySelector('[data-bs-toggle="collapse"]')
+          if (toggleBtn) toggleBtn.setAttribute('aria-expanded', 'true')
+        }
+
+        dataItem.replaceWith(newItem)
+      })
+      .catch(() => {})
+  }
+}

app/policies/object_policy.rb

@@ -12,4 +12,8 @@ def show?
   def edit?
     false
   end
+
+  def edit_description?
+    admin?
+  end
 end