ecoportal-api-graphql 1.3.16 → 2.2.0

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,8 +1,11 @@
-module Ecoportal::API::GraphQL::Base::Page
+module Ecoportal::API::GraphQL::Base::Page
   class DataField
     # Image gallery field.
-    # Writing requires a prior file upload to the REST upload endpoint
-    # to obtain fileContainerIds — see the file-upload TODO in projects/TODO.md.
+    # ★ 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`.
     class ImageGallery < DataField
       passarray :fileContainers # each: { id:, fileName:, url:, ... }
 

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/people.rb

@@ -4,20 +4,16 @@ module Ecoportal::API::GraphQL::Base::Page
       passarray :peopleIds
 
       def people_ids
-        ids = Array(peopleIds)
-        return ids unless ids.empty?
-
-        # Fallback: the read fragment populates `peopleIds`, but if a response ever returns it
-        # null/empty while the expanded `people { id }` nodes ARE present (a partial / non-
-        # $content read), seed from the nodes. The backend write replaces peopleIds wholesale,
-        # so a `people_ids << x` append must start from the existing set or it would WIPE the
-        # field. Mirrors CrossReference's references.nodes fallback. Read key == write key
-        # (peopleIds), so this only widens the read; it never creates phantom-dirty.
-        Array(doc['people']).map { |p| p.is_a?(Hash) ? p['id'] : p }.compact
+        people_ids_from(doc)
       end
 
       def people_ids=(ids)
-        doc['peopleIds'] = Array(ids).compact
+        # An explicit write makes `peopleIds` authoritative for THIS instance: without the
+        # flag, a deliberate clear (`people_ids = []`) on a `peopleIds: null` baseline would
+        # fall back to the `people` nodes on the doc side too, compare equal, and be silently
+        # dropped. The flag confines the fallback to un-written docs.
+        @people_ids_written  = true
+        doc['peopleIds']     = Array(ids).compact
       end
 
       # v2 compat: scripts may set via people_ids= or direct assignment
@@ -25,10 +21,52 @@ module Ecoportal::API::GraphQL::Base::Page
         self.people_ids = ids
       end
 
+      # Dirty only when the effective people-id SET actually changed.
+      #
+      # The read response can carry `peopleIds: null` while still populating the expanded
+      # `people { id }` (and `cachedPeople`) nodes (a partial / non-$content read). The
+      # default key-level leaf diff baselines on `original_doc['peopleIds']` (null), so
+      # writing the SAME id set as already attached looks like a brand-new key and flags
+      # a change — a phantom-dirty update that sends `peopleIds` for a no-op. Compare id
+      # SETS (falling back to `people[].id` on both sides) instead. Mirrors CrossReference's
+      # `references.nodes` fallback / `dirty?` override for the identical disease.
+      def dirty?
+        effective_people_ids.sort != people_ids_from(original_doc).sort
+      end
+
       def as_input
         return nil unless dirty?
 
-        { people: { id: id, peopleIds: Array(peopleIds) } }
+        { people: { id: id, peopleIds: effective_people_ids } }
+      end
+
+      private
+
+      # The id set the client currently means: after an explicit `people_ids=` write the raw
+      # `peopleIds` doc key is authoritative (so `[]` means CLEAR, no fallback); before any
+      # write it is the shape-agnostic read (fallback to `people[].id` nodes). Keeping
+      # `as_input` on the same source as `dirty?` also prevents an explicit clear from
+      # re-serialising fallback-seeded node ids.
+      def effective_people_ids
+        return Array(doc['peopleIds']).compact if @people_ids_written
+
+        people_ids_from(doc)
+      end
+
+      # Extract the people id set from a doc snapshot. `original_doc` is the server baseline
+      # (the diff prev_doc — see Diffable::ClassicDiffService), `doc` carries client changes.
+      # Prefer `peopleIds` when it is present and non-empty (the write shape, and the normal
+      # read shape); fall back to the expanded `people[].id` nodes (the read-only lookup
+      # shape) when `peopleIds` is absent/null/empty — so the comparison is shape-agnostic on
+      # both sides and stays correct after `consolidate!` copies `doc` into `original_doc`.
+      # `people` nodes are a lookup only, never written.
+      def people_ids_from(source_doc)
+        return [] unless source_doc
+
+        ids = Array(source_doc['peopleIds']).compact
+        return ids unless ids.empty?
+
+        Array(source_doc['people']).map { |p| p.is_a?(Hash) ? p['id'] : p }.compact
       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

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

@@ -10,24 +10,12 @@ module Ecoportal
             #
             # A DataField's array attributes (`options`, `peopleIds`, `contractors`,
             # `pages`, `fileContainers`, `items`, ...) are declared with `passarray`,
-            # which registers them as *cascaded* attributes. The default `DiffService`
-            # strips cascaded keys from the flat classic diff (`doc_with_non_cascaded_attributes`)
-            # on the assumption that a later `diff_reduce` pass re-adds them by cascading
-            # into nested `GraphQL::Model` children. DataField arrays are plain hashes /
-            # strings, not `GraphQL::Model` objects, so that re-add never happens and the
-            # array change becomes invisible to the diff (scalar `passthrough` fields are
-            # unaffected). For a leaf model we want every doc key diffed inline, so this
-            # service keeps cascaded keys in place.
-            class LeafDiffService < Ecoportal::API::Common::GraphQL::Model::Diffable::DiffService
-              private
-
-              # Keep all doc keys: leaf-field arrays are data, not nested models.
-              def doc_with_non_cascaded_attributes(json)
-                json
-              end
-            end
-
-            DIFF_CLASS = LeafDiffService
+            # which registers them as *cascaded* attributes invisible to the default
+            # `DiffService` (see `Diffable::LeafDiffService` for the full explanation).
+            # A DataField is a pure leaf model (no nested `GraphQL::Model` children), so
+            # it diffs `flat: true` — the promoted shared `LeafDiffService` keeps the
+            # array doc keys inline.
+            DIFF_CLASS = Ecoportal::API::Common::GraphQL::Model::Diffable::LeafDiffService
             # Map GraphQL __typename values to subclass names.
             TYPE_MAP = {
               'PlainText'          => 'PlainText',
@@ -55,6 +43,12 @@ module Ecoportal
 
             passkey :id
             passthrough :label, :deindex, :genomeSignature
+            # `read_only: true` is load-bearing, not documentation: `description` is readable on
+            # `DataFieldsInterface` but ABSENT from `DataFieldInput` and every per-type member of
+            # it, so a writable accessor would make the field dirty and push a key `updatePage`
+            # cannot accept. The only writer is the `editFieldConfiguration` workflow command
+            # (`Input::WorkflowCommand::EditFieldConfiguration`).
+            passthrough :description, read_only: true
             # __typename is stored under the 'type' key after mapping
             passthrough :type
 

data/lib/ecoportal/api/graphql/base/page/phased/stage.rb

@@ -10,6 +10,9 @@ module Ecoportal
               passkey :id
               passthrough :name, :ordering, :state
               passboolean :active, :started
+              # Per-stage tag set (Stage.tags in the schema). Fetched by the stageAttrs
+              # fragment; a component of #all_tags. Empty array when not queried.
+              passarray :tags
 
               class_resolver :callback_type_class, 'Ecoportal::API::GraphQL::Base::PagesWorkflow::CallbackType'
 
@@ -17,6 +20,54 @@ module Ecoportal
               # canonical field objects (filtered to this stage) rather than fresh dups.
               attr_writer :page_field_collection
 
+              # The owning page, resolved via the DoubleModel's NATIVE nesting reference rather
+              # than a manually-injected back-ref. A stage is embedded under the page as
+              # page -> stages (CollectionModel) -> stage, so `_parent` is the intermediate
+              # collection, NOT the page. `root` walks the whole `_parent` chain to the top of
+              # the doc model (the page), which is robust to that intermediate nesting.
+              #
+              # Returns the page for an embedded stage, or nil for a standalone stage whose root
+              # is itself (i.e. not a page — has no baseTags/otherTags/location_ids to fold in).
+              def page
+                top = root
+                top.equal?(self) ? nil : top
+              end
+
+              # location_ids redirect: the GraphQL Stage type has NO location field — locations
+              # are assigned at the PAGE level (page.locations { id }). So a stage's location ids
+              # are the page's location ids. Empty array for a standalone stage.
+              def location_ids
+                Array(page&.location_ids)
+              end
+
+              # The stage's fully-compiled tag set (client-side build of the backend-only
+              # "compiled_tags"), per the domain formula:
+              #
+              #   Stage.all_tags = page.baseTags + page.location_ids + page.otherTags + stage.tags
+              #
+              # (page.location_ids — surfaced here via #location_ids — stands in for the per-stage
+              #  "location_ids" of the formula: the GraphQL schema does NOT expose locations on the
+              #  Stage type, they are assigned at the PAGE level.)
+              #
+              # Returns a de-duplicated Array of tag strings. For a standalone stage (no owning
+              # page) folds in only the stage's own tags.
+              def all_tags
+                (page_base_tags + location_ids + page_other_tags + Array(tags)).
+                  compact.uniq
+              end
+
+              private
+
+              def page_base_tags
+                page ? Array(page.baseTags) : []
+              end
+
+              def page_other_tags
+                page ? Array(page.otherTags) : []
+              end
+
+              public
+
               def workflow_callbacks
                 @workflow_callbacks ||= Array(doc['workflowCallbacks'] || []).map { |cb| callback_type_class.from_doc(cb) }
               end

data/lib/ecoportal/api/graphql/base/page/phased.rb

@@ -1,15 +1,15 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        module Page
-          class Phased < Interface::BasePage
-            require_relative 'phased/stage'
-
-            embeds_many :stages, klass: Stage, read_only: true
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Page
+          class Phased < Interface::BasePage
+            require_relative 'phased/stage'
+
+            embeds_many :stages, klass: Stage, read_only: true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/section.rb

@@ -1,48 +1,48 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        module Page
-          # Wraps a SectionUnion doc (ContentSection or SplitSection).
-          # Provides access to heading, type, and data fields within the section.
-          class Section < Logic::BaseModel
-            read_only!
-
-            passkey :id
-            passthrough :heading
-
-            # __typename normalised to 'type' during initialisation
-            passthrough :type
-
-            def initialize(raw_doc = {})
-              raw_doc = raw_doc.dup if raw_doc.is_a?(Hash)
-              raw_doc['type'] ||= raw_doc['__typename'] if raw_doc.is_a?(Hash)
-              super
-            end
-
-            # All data fields in this section.
-            # ContentSection  → dataFields
-            # SplitSection    → leftDataFields + rightDataFields (merged)
-            def components
-              all = (doc['dataFields']      || []) +
-                    (doc['leftDataFields']  || []) +
-                    (doc['rightDataFields'] || [])
-              DataField::Collection.from_doc(all)
-            end
-
-            # v2 compat alias
-            alias_method :data_fields, :components
-
-            def content_section?
-              type.to_s == 'ContentSection'
-            end
-
-            def split_section?
-              type.to_s == 'SplitSection'
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Page
+          # Wraps a SectionUnion doc (ContentSection or SplitSection).
+          # Provides access to heading, type, and data fields within the section.
+          class Section < Logic::BaseModel
+            read_only!
+
+            passkey :id
+            passthrough :heading
+
+            # __typename normalised to 'type' during initialisation
+            passthrough :type
+
+            def initialize(raw_doc = {})
+              raw_doc = raw_doc.dup if raw_doc.is_a?(Hash)
+              raw_doc['type'] ||= raw_doc['__typename'] if raw_doc.is_a?(Hash)
+              super
+            end
+
+            # All data fields in this section.
+            # ContentSection  → dataFields
+            # SplitSection    → leftDataFields + rightDataFields (merged)
+            def components
+              all = (doc['dataFields']      || []) +
+                    (doc['leftDataFields']  || []) +
+                    (doc['rightDataFields'] || [])
+              DataField::Collection.from_doc(all)
+            end
+
+            # v2 compat alias
+            alias_method :data_fields, :components
+
+            def content_section?
+              type.to_s == 'ContentSection'
+            end
+
+            def split_section?
+              type.to_s == 'SplitSection'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page_info.rb

@@ -1,12 +1,12 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        class PageInfo < Logic::BaseModel
-          passthrough :startCursor, :endCursor
-          passboolean :hasNextPage, :hasPreviousPage
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class PageInfo < Logic::BaseModel
+          passthrough :startCursor, :endCursor
+          passboolean :hasNextPage, :hasPreviousPage
+        end
+      end
+    end
+  end
+end