ecoportal-api-graphql 2.0.0 → 3.0.0

data/lib/ecoportal/api/graphql/base/page/data_field/ai_summary.rb

@@ -1,18 +1,18 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # AI-generated summary field.
-    # Content is generated server-side via generateAiSummary mutation (Bedrock Claude).
-    # Not settable via DataFieldInput — use the dedicated mutation instead.
-    #
-    # instructions: the AI prompt configured on this field in the template.
-    # trigger: "submitted" | "approved" — when generation fires.
-    # trigger_stage_ids: stages that trigger generation (empty = all stages).
-    # text_format: "simple_text" | "bullet_points" | "numbered_list" | "headings"
-    class AiSummary < DataField
-      passthrough :aiSummary, :generatedAt, :instructions
-      passthrough :trigger, :textFormat
-      passarray   :triggerStageIds, :fieldConfigurations
-      passboolean :alreadyRated
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # AI-generated summary field.
+    # Content is generated server-side via generateAiSummary mutation (Bedrock Claude).
+    # Not settable via DataFieldInput — use the dedicated mutation instead.
+    #
+    # instructions: the AI prompt configured on this field in the template.
+    # trigger: "submitted" | "approved" — when generation fires.
+    # trigger_stage_ids: stages that trigger generation (empty = all stages).
+    # text_format: "simple_text" | "bullet_points" | "numbered_list" | "headings"
+    class AiSummary < DataField
+      passthrough :aiSummary, :generatedAt, :instructions
+      passthrough :trigger, :textFormat
+      passarray   :triggerStageIds, :fieldConfigurations
+      passboolean :alreadyRated
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/checklist.rb

@@ -1,29 +1,29 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    class Checklist < DataField
-      passarray :items # each: { id:, label:, checked: }
-      passthrough :complete
-
-      # Check/uncheck an item by label or id.
-      def check(label_or_id, checked: true)
-        item = (doc['items'] || []).find { |i| i['label'] == label_or_id.to_s || i['id'] == label_or_id.to_s }
-        return unless item
-
-        item['checked'] = checked
-      end
-
-      def as_input
-        return nil unless dirty?
-
-        {
-          checklist: {
-            id:    id,
-            # rubocop:disable Style/DoubleNegation
-            items: (doc['items'] || []).map { |i| { id: i['id'], checked: !!i['checked'] } }
-            # rubocop:enable Style/DoubleNegation
-          }
-        }
-      end
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class Checklist < DataField
+      passarray :items # each: { id:, label:, checked: }
+      passthrough :complete
+
+      # Check/uncheck an item by label or id.
+      def check(label_or_id, checked: true)
+        item = (doc['items'] || []).find { |i| i['label'] == label_or_id.to_s || i['id'] == label_or_id.to_s }
+        return unless item
+
+        item['checked'] = checked
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        {
+          checklist: {
+            id:    id,
+            # rubocop:disable Style/DoubleNegation
+            items: (doc['items'] || []).map { |i| { id: i['id'], checked: !!i['checked'] } }
+            # rubocop:enable Style/DoubleNegation
+          }
+        }
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/collection.rb

@@ -31,7 +31,7 @@ module Ecoportal::API::GraphQL::Base::Page
 
       # Find first field matching label (case-insensitive). Optional type: restricts to
       # that field type first (v2 compat: components.get_by_name(name, type:) — used by
-      # the farmers cutover use case which calls it directly, not via OozeRedirect).
+      # a customer cutover use case which calls it directly, not via OozeRedirect).
       def get_by_name(label, type: nil)
         pool = type ? get_by_type(type) : @fields
         pool.find { |f| f.label.to_s.downcase == label.to_s.downcase }

data/lib/ecoportal/api/graphql/base/page/data_field/cross_reference.rb

@@ -1,4 +1,4 @@
-module Ecoportal::API::GraphQL::Base::Page
+module Ecoportal::API::GraphQL::Base::Page
   class DataField
     # Cross-reference field — links to pages in another register.
     class CrossReference < DataField

data/lib/ecoportal/api/graphql/base/page/data_field/date_field.rb

@@ -1,23 +1,23 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # Wraps Date data field. Mapped from __typename 'Date'.
-    # value is an ISO8601DateTime string (e.g. "2024-11-25T08:30:00+13:00").
-    class DateField < DataField
-      # value is nested: { dateTime: "...", timeZone: "..." } or raw string
-      def value
-        v = doc['value']
-        v.is_a?(Hash) ? v['dateTime'] : v
-      end
-
-      def value=(iso8601_string)
-        doc['value'] = iso8601_string
-      end
-
-      def as_input
-        return nil unless dirty?
-
-        { date: { id: id, value: value } }
-      end
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Wraps Date data field. Mapped from __typename 'Date'.
+    # value is an ISO8601DateTime string (e.g. "2024-11-25T08:30:00+13:00").
+    class DateField < DataField
+      # value is nested: { dateTime: "...", timeZone: "..." } or raw string
+      def value
+        v = doc['value']
+        v.is_a?(Hash) ? v['dateTime'] : v
+      end
+
+      def value=(iso8601_string)
+        doc['value'] = iso8601_string
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { date: { id: id, value: value } }
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/geo.rb

@@ -1,24 +1,24 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    class Geo < DataField
-      passthrough :address, :coordinates # coordinates: { lat:, lon: }
-
-      def address=(new_address)
-        doc['address'] = new_address
-      end
-
-      def coordinates=(lat_lon_hash)
-        doc['coordinates'] = lat_lon_hash
-      end
-
-      def as_input
-        return nil unless dirty?
-
-        payload = { id: id }
-        payload[:address]     = address     if address
-        payload[:coordinates] = coordinates if coordinates
-        { geo: payload }
-      end
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class Geo < DataField
+      passthrough :address, :coordinates # coordinates: { lat:, lon: }
+
+      def address=(new_address)
+        doc['address'] = new_address
+      end
+
+      def coordinates=(lat_lon_hash)
+        doc['coordinates'] = lat_lon_hash
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        payload = { id: id }
+        payload[:address]     = address     if address
+        payload[:coordinates] = coordinates if coordinates
+        { geo: payload }
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/image_gallery.rb

@@ -1,26 +1,174 @@
-module Ecoportal::API::GraphQL::Base::Page
+module Ecoportal::API::GraphQL::Base::Page
   class DataField
     # Image gallery field.
-    # ★ WRITE PATH BROKEN (schema-invalid, live-verified 2026-08): `ImageGalleryInput` has no
-    # `fileContainerIds` — it takes `images: [ImageInput]`, attaching via `sourceId`, which is
-    # an `Enzyme::ImageReference::TempImage` (a DIFFERENT upload pipeline than file containers).
-    # Fixing this needs its own design — see the DataField shape-asymmetry review project.
-    # The reader is equally stale: live responses carry `images`, not `fileContainers`.
+    #
+    # ★ FIXED 2026-09 (previously broken -- see `spec/.../image_gallery_characterization_spec.rb`
+    # git history for the prior "WRITE PATH BROKEN" documentation of this defect). Confirmed
+    # against the LIVE ecoPortal server source (read-only, /tmp/work/ecoPortal) that a
+    # gallery image is genuinely NOT a `FileContainer`:
+    #   * `app/graphql/types/fill_in_page/inputs/data_fields/image_gallery_input.rb:5-11` --
+    #     `ImageGalleryInput` has NO `fileContainerIds`; it takes `images: [ImageInput]`.
+    #   * `.../image_galleries/image_input.rb:6-15` -- `ImageInput` takes `sourceId` (a
+    #     `TempImage` id, from the SEPARATE `uploadImage` mutation -- see
+    #     `Mutation::Image::Upload` / `FileUpload::Client#upload_image`), never
+    #     `fileContainerId`.
+    #   * `app/services/new_ep/pages/assign_attributes_service.rb:152-176`
+    #     (`set_image_gallery_attrs`) -- full-replace-by-omission, the SAME trap as
+    #     `FileField`: any current image whose `id` is not echoed back in the write is
+    #     destroyed (`format_removed_ids`).
+    #   * `app/graphql/types/pages/data_fields/image_galleries/image_type.rb` -- `fileName`/
+    #     `fileSize` are NULLABLE even on a successful upload -- a documented upstream bug
+    #     ("images are successfully uploaded but the file name and size are not set in the
+    #     database", per the live schema's own field comment). Any comparison built on these
+    #     two fields must treat a nil on either side as "not a confident match", never a
+    #     positive one.
+    #
+    # READ: `images { id weight downloadUrl caption fileName fileSize uploadId }`
+    # (`imageGalleryField` fragment, `fragment/pages/common_page_union.rb` -- `id`/`weight`
+    # were ADDED alongside this fix; the fragment previously omitted both, which is why no
+    # correct reader was possible before now).
+    #
+    # WRITE: `ImageGalleryInput { id images: [ImageInput] }`; `ImageInput { id weight
+    # sourceId caption fileName sensitiveContent inaccurateDescription
+    # inaccurateExtractedText }`. `as_input` sends every KEPT image back with its FULL
+    # `ImageInput` field set (`#kept_image_input`) -- NOT a bare `{id:}` -- and every NEW one
+    # as `{sourceId:, weight:, fileName:}` -- see `#add_source_images`, the merge-safe writer
+    # (mirrors `FileField#file_container_ids=`'s kept-vs-new split).
+    #
+    # ★ CORRECTED 2026-09 (pre-release, MR !278 unreleased): the bare `{id:}` echo for a kept
+    # image, above, silently dropped every OTHER attribute on that image on the NEXT write
+    # server-side -- `assign_attributes_service.rb#set_image_gallery_attrs` applies `images`
+    # as a FULL REPLACE (see the class header above), so a bare `{id:}` is indistinguishable
+    # from "clear caption/sensitiveContent/etc back to their defaults" for that image, not
+    # "leave it as it is". Matches the org-side reference implementation (a downstream script repo,
+    # commit 482db9c) and the live schema's own `ImageInput` argument list -- the shipped
+    # `ep-api-collections` sample only demonstrates the NEW-image shape (no existing images to
+    # keep), so this shape is pinned to server source + that proven reference, not a captured
+    # kept-echo payload (see EVIDENCE PRECEDENCE note on `#kept_image_input`).
+    #
+    # `images` is deliberately a PLAIN doc reader, not `passarray` -- same reasoning as
+    # `FileField#items` (see that class's header): materialising an ArrayModel writes
+    # `images: []` into the doc of a field read without `$content`, and a phantom-dirty empty
+    # `images` here doesn't always no-op (only the empty-vs-missing-key case is neutralised
+    # by `Diffable::LeafDiffService`'s array-diff fix, MR !106) -- it can still synthesise an
+    # unwanted write for a non-empty phantom read. A plain reader has no such hazard.
     class ImageGallery < DataField
-      passarray :fileContainers # each: { id:, fileName:, url:, ... }
+      # each: { 'id' =>, 'weight' =>, 'downloadUrl' =>, 'caption' =>, 'fileName' =>,
+      #         'fileSize' =>, 'uploadId' => }
+      def images
+        Array(doc['images'])
+      end
+
+      # @return [Array<String>] every image's own item id (its server-assigned id, NOT the
+      #   `uploadId`/`TempImage` id it was created from).
+      def image_ids
+        images.filter_map { |image| image['id'] if image.is_a?(Hash) }
+      end
 
-      def file_container_ids
-        Array(fileContainers).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+      # @return [Integer] one past the highest `weight` currently on the field (`0` if the
+      #   field is empty). There is no server-side auto-increment for `weight` (a plain
+      #   Integer field, default `0`) -- callers that want sequential ordering for several new
+      #   images in one write should still call this ONCE and increment locally
+      #   (`#add_source_images` already does).
+      def next_weight
+        return 0 if images.empty?
+
+        images.map { |image| image.is_a?(Hash) ? image['weight'].to_i : 0 }.max + 1
       end
 
-      def file_container_ids=(ids)
-        doc['fileContainers'] = Array(ids).map { |id_val| { 'id' => id_val } }
+      # Merge-safe write: adds NEW images (each referenced by `source_id`, the `TempImage`
+      # id from `FileUpload::Client#upload_image`) while KEEPING every image already loaded
+      # on this field. `images` on `ImageGalleryInput` is a FULL REPLACE server-side -- any
+      # current image whose `id` is not echoed back is destroyed -- so this always keeps
+      # every currently-loaded image's FULL doc entry (untouched -- `#images_input` picks the
+      # `ImageInput`-writable subset out of it later; kept HERE in full so that subset still
+      # has every field to read, rather than collapsing to a bare `{'id' => ...}` that would
+      # throw the other attributes away before `#as_input` ever runs) and appends the new
+      # ones after it, at sequential weights starting at `#next_weight`. Marks the field dirty
+      # (same underlying mechanism as `FileField#file_container_ids=` -- a raw `doc` mutation,
+      # picked up by the generic diff regardless of the `passarray`/plain-reader choice above).
+      #
+      # @param sources [Array<Hash>] one entry per NEW image. Accepts either key style:
+      #   `{source_id:, file_name:}` or `{'sourceId' =>, 'fileName' =>}`. `weight` is assigned
+      #   here, not read from the input -- the caller does not need to compute it.
+      # @return [Array<Hash>] the full resulting `images` doc (kept + added), same value now
+      #   readable via `#images`.
+      def add_source_images(sources)
+        kept  = images.select { |image| image.is_a?(Hash) && image['id'] }
+        start = next_weight
+        added = Array(sources).each_with_index.map do |source, index|
+          {
+            'sourceId' => fetch_key(source, :source_id, 'sourceId'),
+            'weight'   => start + index,
+            'fileName' => fetch_key(source, :file_name, 'fileName')
+          }.compact
+        end
+        doc['images'] = kept + added
       end
 
       def as_input
         return nil unless dirty?
 
-        { imageGallery: { id: id, fileContainerIds: file_container_ids } }
+        {imageGallery: {id: id, images: images_input}}
+      end
+
+      private
+
+      # `images` holds the write shape for a NEW item (`{'sourceId' =>, 'weight' =>,
+      # 'fileName' =>}`, from `#add_source_images`) as-is, and the FULL read doc for a KEPT
+      # item (untouched since the last read) -- `#kept_image_input` narrows the latter down to
+      # exactly what `ImageInput` accepts.
+      def images_input
+        images.filter_map do |image|
+          next unless image.is_a?(Hash)
+
+          if image['sourceId']
+            {sourceId: image['sourceId'], weight: image['weight'], fileName: image['fileName']}.compact
+          elsif image['id']
+            kept_image_input(image)
+          end
+        end
+      end
+
+      # Full-field echo for a KEPT (currently-existing, untouched) image -- REQUIRED because
+      # `ImageGalleryInput.images` is a full replace server-side (`assign_attributes_service.
+      # rb#set_image_gallery_attrs` -> `format_removed_ids`): a bare `{id:}` is read by the
+      # server as "clear every other attribute", not "leave this image as it is".
+      #
+      # EVIDENCE PRECEDENCE (shipped sample -> server source -> gem model): the shipped
+      # a customer collection's "Attach Image to Gallery Field"
+      # sample only demonstrates a BRAND-NEW image (`sourceId`/`weight`/`fileName`, no
+      # existing images on the field to keep) -- it does not capture a kept-image echo. This
+      # shape is therefore pinned to the next level down: the live schema's own `ImageInput`
+      # argument list (`app/graphql/types/fill_in_page/inputs/data_fields/image_galleries/
+      # image_input.rb`: `id weight sourceId caption fileName sensitiveContent
+      # inaccurateDescription inaccurateExtractedText`) plus the org-side reference
+      # implementation already built against those same server facts and merged
+      # (a downstream script repo, commit 482db9c, `#kept_gallery_image_input`) -- not an inference
+      # from this gem's own prior (incorrect) behaviour.
+      #
+      # `sourceId` here is read back from the CURRENT read's `uploadId` -- the read-side name
+      # for the same identifier (a customer collection's integration guide
+      # section 7: "the id changes name between reading and writing"). Every key is sent as
+      # read (never `.compact`-ed away) -- this is an ECHO of the field's current state, so a
+      # nil here means "this attribute is genuinely unset", which is exactly what should be
+      # (re-)written to preserve it unset, not omitted and misread as "clear it".
+      def kept_image_input(image)
+        {
+          id:                      image['id'],
+          sourceId:                image['uploadId'],
+          weight:                  image['weight'],
+          caption:                 image['caption'],
+          fileName:                image['fileName'],
+          sensitiveContent:        image['sensitiveContent'],
+          inaccurateDescription:   image['inaccurateDescription'],
+          inaccurateExtractedText: image['inaccurateExtractedText']
+        }
+      end
+
+      def fetch_key(hash, *keys)
+        keys.each { |k| return hash[k] if hash.is_a?(Hash) && hash.key?(k) }
+        nil
       end
     end
   end

data/lib/ecoportal/api/graphql/base/page/data_field/law.rb

@@ -1,8 +1,8 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # Legal obligation / law snippets field — read access only.
-    class Law < DataField
-      passarray :laws # each: { id:, content: }
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Legal obligation / law snippets field — read access only.
+    class Law < DataField
+      passarray :laws # each: { id:, content: }
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/mailbox.rb

@@ -1,9 +1,9 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # Mailbox field — email inbox linked to this field.
-    # Managed by the system; not settable via script.
-    class Mailbox < DataField
-      passthrough :email, :enabled
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Mailbox field — email inbox linked to this field.
+    # Managed by the system; not settable via script.
+    class Mailbox < DataField
+      passthrough :email, :enabled
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/plain_text.rb

@@ -1,17 +1,17 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    class PlainText < DataField
-      passthrough :value
-
-      def value=(new_value)
-        doc['value'] = new_value
-      end
-
-      def as_input
-        return nil unless dirty?
-
-        { plainText: { id: id, value: value } }
-      end
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class PlainText < DataField
+      passthrough :value
+
+      def value=(new_value)
+        doc['value'] = new_value
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { plainText: { id: id, value: value } }
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/rich_text.rb

@@ -1,26 +1,26 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    class RichText < DataField
-      passthrough :content
-
-      def content=(new_content)
-        doc['content'] = new_content
-      end
-
-      # v2 compat alias — RichText value is stored as content
-      def value
-        content
-      end
-
-      def value=(new_value)
-        self.content = new_value
-      end
-
-      def as_input
-        return nil unless dirty?
-
-        { richText: { id: id, content: content } }
-      end
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class RichText < DataField
+      passthrough :content
+
+      def content=(new_content)
+        doc['content'] = new_content
+      end
+
+      # v2 compat alias — RichText value is stored as content
+      def value
+        content
+      end
+
+      def value=(new_value)
+        self.content = new_value
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { richText: { id: id, content: content } }
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/signature.rb

@@ -1,9 +1,9 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # Digital signature capture field — read access only.
-    # Signatures are captured through the UI; not settable via script.
-    class Signature < DataField
-      passthrough :signedAt, :signerName
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Digital signature capture field — read access only.
+    # Signatures are captured through the UI; not settable via script.
+    class Signature < DataField
+      passthrough :signedAt, :signerName
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/smart_fill.rb

@@ -1,17 +1,17 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # SmartFill field — AI-auto-populated field using a template-defined prompt.
-    # Value is generated server-side via Bedrock; trigger_type controls when.
-    #
-    # Read-only for DataFieldInput — use the generateSmartFill GraphQL mutation
-    # (or its trigger) to populate. The instructions field is template-configured
-    # and can be reviewed/updated via template management.
-    class SmartFill < DataField
-      passthrough :status        # pending | generating | success | failed
-      passthrough :trigger_type  # manual | snapshot | live
-      passthrough :instructions  # the AI prompt configured on the template field
-      passboolean :edit_enabled
-      passthrough :generated_at
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # SmartFill field — AI-auto-populated field using a template-defined prompt.
+    # Value is generated server-side via Bedrock; trigger_type controls when.
+    #
+    # Read-only for DataFieldInput — use the generateSmartFill GraphQL mutation
+    # (or its trigger) to populate. The instructions field is template-configured
+    # and can be reviewed/updated via template management.
+    class SmartFill < DataField
+      passthrough :status        # pending | generating | success | failed
+      passthrough :trigger_type  # manual | snapshot | live
+      passthrough :instructions  # the AI prompt configured on the template field
+      passboolean :edit_enabled
+      passthrough :generated_at
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/table.rb

@@ -1,9 +1,9 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # Table / embedded structure field — read access only.
-    # Complex structured data managed via its own mutation path.
-    class Table < DataField
-      passarray :rows
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Table / embedded structure field — read access only.
+    # Complex structured data managed via its own mutation path.
+    class Table < DataField
+      passarray :rows
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/tag_field.rb

@@ -1,21 +1,21 @@
-module Ecoportal::API::GraphQL::Base::Page
-  class DataField
-    # Location/tag field — mapped from __typename 'TagField'.
-    class TagField < DataField
-      passarray :locations # each: { id:, name: }
-
-      def location_ids
-        Array(locations).map { |l| l['id'] }.compact
-      end
-
-      def location_ids=(ids)
-        doc['locations'] = Array(ids).map { |id_val| { 'id' => id_val } }
-      end
-
-      # NOTE: LocationFieldInput has NO location-value field — page locations are set at the
-      # PAGE level (UpdatePageInput.page.locations, via Interface::BasePage#location_ids=),
-      # not via the data field. So this field contributes no value to dataFields.updates;
-      # it inherits DataField#as_input (nil). location_ids/= stay as field-level read/staging.
-    end
-  end
-end
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Location/tag field — mapped from __typename 'TagField'.
+    class TagField < DataField
+      passarray :locations # each: { id:, name: }
+
+      def location_ids
+        Array(locations).map { |l| l['id'] }.compact
+      end
+
+      def location_ids=(ids)
+        doc['locations'] = Array(ids).map { |id_val| { 'id' => id_val } }
+      end
+
+      # NOTE: LocationFieldInput has NO location-value field — page locations are set at the
+      # PAGE level (UpdatePageInput.page.locations, via Interface::BasePage#location_ids=),
+      # not via the data field. So this field contributes no value to dataFields.updates;
+      # it inherits DataField#as_input (nil). location_ids/= stay as field-level read/staging.
+    end
+  end
+end