ecoportal-api-graphql 1.3.4 → 1.3.9

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

@@ -0,0 +1,54 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Cross-reference field — links to pages in another register.
+    class CrossReference < DataField
+      passarray :pages # staged writes; the READ response uses `references` (a connection)
+
+      # Current reference ids. The GraphQL response carries them under `references.nodes`
+      # (CommonPageUnion's crossReferenceField), NOT `pages` — so read from there. After a
+      # page_ids= write, prefer the staged `pages` value.
+      def page_ids
+        ref_ids_from(doc)
+      end
+
+      def page_ids=(ids)
+        doc['pages'] = Array(ids).map { |id_val| { 'id' => id_val } }
+      end
+
+      # Dirty only when the effective reference-id SET actually changed.
+      #
+      # The field is READ into `references.nodes` but WRITTEN via `pages` (page_ids=). The
+      # default key-level leaf diff therefore sees a brand-new `pages` key the moment any
+      # setter runs and flags a change — even when the set is unchanged. The common offender
+      # is `clear` on an already-empty field ([] -> []): eco-helpers scripts clear a reference
+      # whenever the source value is blank, which under APIv2 was a no-op but on GraphQL
+      # emitted a phantom `referenceIds: []` update. Compare id SETS against the server
+      # baseline (`original_doc`) instead — restoring v2 parity (empty->empty / same->same
+      # is not dirty).
+      def dirty?
+        ref_ids_from(doc).sort != ref_ids_from(original_doc).sort
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        # CrossReferenceInput uses `referenceIds` (schema-confirmed) — NOT pageIds.
+        { crossReference: { id: id, referenceIds: page_ids } }
+      end
+
+      private
+
+      # Extract the reference id set from a doc snapshot. `original_doc` is the server baseline
+      # (the diff prev_doc — see Diffable::ClassicDiffService), `doc` carries client changes.
+      # Both prefer the staged `pages` (write shape) and fall back to `references.nodes` (read
+      # shape) — so the comparison is shape-agnostic and stays correct after `consolidate!`
+      # copies `doc` (with `pages`) into `original_doc`.
+      def ref_ids_from(source_doc)
+        return [] unless source_doc
+
+        src = source_doc.key?('pages') ? source_doc['pages'] : Array(source_doc.dig('references', 'nodes'))
+        Array(src).map { |r| r.is_a?(Hash) ? r['id'] : r }.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +1,25 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # File attachment field.
+    # Writing requires a prior file upload to the REST upload endpoint
+    # to obtain fileContainerIds — see the file-upload TODO in projects/TODO.md.
+    # The file_container_ids= setter can be used once IDs are available.
+    class FileField < DataField
+      passarray :fileContainers # each: { id:, fileName:, ... }
+
+      def file_container_ids
+        Array(fileContainers).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+      end
+
+      def file_container_ids=(ids)
+        doc['fileContainers'] = Array(ids).map { |id_val| { 'id' => id_val } }
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { file: { id: id, fileContainerIds: file_container_ids } }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class Gauge < DataField
+      passthrough :value, :max
+
+      # Blank (empty / whitespace CSV cell) → nil, NOT 0.0 — see DataField#numeric_or_nil
+      # (mirrors Number; `"".to_f` would otherwise silently write a real zero).
+      def value=(numeric)
+        doc['value'] = numeric_or_nil(numeric)
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { gauge: { id: id, value: value } }
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +1,24 @@
+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.
+    class ImageGallery < DataField
+      passarray :fileContainers # each: { id:, fileName:, url:, ... }
+
+      def file_container_ids
+        Array(fileContainers).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+      end
+
+      def file_container_ids=(ids)
+        doc['fileContainers'] = Array(ids).map { |id_val| { 'id' => id_val } }
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { imageGallery: { id: id, fileContainerIds: file_container_ids } }
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +1,20 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class Number < DataField
+      passthrough :value
+
+      # Blank (empty / whitespace CSV cell) → nil, NOT 0.0 — see DataField#numeric_or_nil.
+      # Whether a blank should CLEAR the field or be LEFT UNTOUCHED is the caller's policy;
+      # this only guarantees a blank never becomes the value 0.0.
+      def value=(numeric)
+        doc['value'] = numeric_or_nil(numeric)
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { number: { id: id, value: value } }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class People < DataField
+      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
+      end
+
+      def people_ids=(ids)
+        doc['peopleIds'] = Array(ids).compact
+      end
+
+      # v2 compat: scripts may set via people_ids= or direct assignment
+      def value=(ids)
+        self.people_ids = ids
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { people: { id: id, peopleIds: Array(peopleIds) } }
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +1,41 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class Select < DataField
+      passarray :options # each: { id:, name:, value:, selected: }
+      passthrough :other, :otherDesc, :multiple, :dataType
+
+      # Select an option by id, name, or value. Deselects all others (single-select).
+      # For multi-select fields, call with multiple values.
+      def select_option(*id_or_values)
+        targets = id_or_values.flatten.map(&:to_s)
+        (doc['options'] || []).each do |opt|
+          opt['selected'] = targets.include?(opt['id'].to_s) ||
+                            targets.include?(opt['name'].to_s) ||
+                            targets.include?(opt['value'].to_s)
+        end
+      end
+
+      # Deselect all options.
+      def clear_selection
+        (doc['options'] || []).each { |opt| opt['selected'] = false }
+      end
+
+      def selected_options
+        (doc['options'] || []).select { |opt| opt['selected'] }
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        {
+          select: {
+            id:      id,
+            # rubocop:disable Style/DoubleNegation
+            options: (doc['options'] || []).map { |opt| { id: opt['id'], selected: !!opt['selected'] } }
+            # rubocop:enable Style/DoubleNegation
+          }
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +1,137 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Page
+          # Base class for all data field types.
+          # Subclasses expose typed value accessors and serialise to DataFieldInput format.
+          class DataField < Logic::BaseModel
+            # Diff strategy for leaf data fields.
+            #
+            # 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
+            # Map GraphQL __typename values to subclass names.
+            TYPE_MAP = {
+              'PlainText'          => 'PlainText',
+              'RichText'           => 'RichText',
+              'Date'               => 'DateField',
+              'Number'             => 'Number',
+              'Gauge'              => 'Gauge',
+              'People'             => 'People',
+              'Select'             => 'Select',
+              'Checklist'          => 'Checklist',
+              'TagField'           => 'TagField',
+              'Geo'                => 'Geo',
+              'Signature'          => 'Signature',
+              'ContractorEntities' => 'ContractorEntities',
+              'CrossReference'     => 'CrossReference',
+              'ImageGallery'       => 'ImageGallery',
+              'File'               => 'FileField',
+              'Mailbox'            => 'Mailbox',
+              'ActionsList'        => 'ActionsList',
+              'Law'                => 'Law',
+              'AiSummary'          => 'AiSummary',
+              'Table'              => 'Table',
+              'SmartFill'          => 'SmartFill'
+            }.freeze
+
+            passkey :id
+            passthrough :label, :deindex
+            # __typename is stored under the 'type' key after mapping
+            passthrough :type
+
+            class << self
+              # Build the correct subclass from a raw field doc.
+              def from_doc(raw_doc)
+                type    = raw_doc.is_a?(Hash) ? (raw_doc['__typename'] || raw_doc['type']) : nil
+                subname = TYPE_MAP[type]
+                klass   = subname ? const_get(subname) : self
+                klass.new(raw_doc)
+              rescue NameError
+                new(raw_doc)
+              end
+            end
+
+            def initialize(raw_doc = {})
+              # Normalise __typename → type for passthrough accessor
+              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
+
+            # DataField is a leaf model: it has no nested GraphQL::Model children.
+            # flat: true skips diff_reduce — required here, since diff_reduce would
+            # dig_delete! the (cascaded) array keys and never re-add them. The flat
+            # classic diff still sees those keys because LeafDiffService keeps them.
+            def dirty?
+              super(flat: true)
+            end
+
+            # Produces the DataFieldInput hash for this field.
+            # Returns nil if the field has not been modified.
+            # Subclasses override to produce typed payloads.
+            def as_input
+              nil
+            end
+
+            private
+
+            # Coerce a value to Float for numeric fields (Number, Gauge), treating a BLANK
+            # (nil / empty / whitespace-only string) as nil — NOT 0.0. Ruby's `"".to_f` is 0.0,
+            # so a naive `numeric&.to_f` silently wrote a real zero whenever a CSV cell was an
+            # empty string (Eco::CSV keeps quoted-empty `""` as "", not nil). A genuine number,
+            # or a numeric string like "0" / "15", still becomes a Float. Shared here so Number
+            # and Gauge cannot drift apart.
+            def numeric_or_nil(value)
+              return value.to_f if value.is_a?(Numeric)
+
+              str = value.to_s.strip
+              str.empty? ? nil : str.to_f
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative 'data_field/plain_text'
+require_relative 'data_field/rich_text'
+require_relative 'data_field/date_field'
+require_relative 'data_field/number'
+require_relative 'data_field/gauge'
+require_relative 'data_field/people'
+require_relative 'data_field/select'
+require_relative 'data_field/checklist'
+require_relative 'data_field/tag_field'
+require_relative 'data_field/geo'
+require_relative 'data_field/signature'
+require_relative 'data_field/contractor_entities'
+require_relative 'data_field/cross_reference'
+require_relative 'data_field/image_gallery'
+require_relative 'data_field/file_field'
+require_relative 'data_field/mailbox'
+require_relative 'data_field/actions_list'
+require_relative 'data_field/law'
+require_relative 'data_field/ai_summary'
+require_relative 'data_field/table'
+require_relative 'data_field/smart_fill'
+require_relative 'data_field/collection'

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

@@ -0,0 +1,68 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Page
+          class Phased
+            # Model for a single stage on a PhasedPage.
+            # Fields match those returned by the stageAttrs fragment in CommonPageUnion.
+            class Stage < Logic::BaseModel
+              passkey :id
+              passthrough :name, :ordering, :state
+              passboolean :active, :started
+
+              class_resolver :callback_type_class, 'Ecoportal::API::GraphQL::Base::PagesWorkflow::CallbackType'
+
+              # Injected by Model::Page::Phased so this stage's #components returns the page's
+              # canonical field objects (filtered to this stage) rather than fresh dups.
+              attr_writer :page_field_collection
+
+              def workflow_callbacks
+                @workflow_callbacks ||= Array(doc['workflowCallbacks'] || []).map { |cb| callback_type_class.from_doc(cb) }
+              end
+
+              # Predicate aliases — eco-helpers scripts call stage.active? / stage.started?
+              def active?
+                !!doc['active']
+              end
+
+              def started?
+                !!doc['started']
+              end
+
+              # Sections in this stage as a SectionCollection.
+              def sections
+                @sections ||= SectionCollection.from_doc(doc['sections'] || [])
+              end
+
+              # All data fields across all sections in this stage (v2 compat: stage.components).
+              # If the parent page injected its canonical field_collection, return THOSE field
+              # objects (filtered to this stage by id) so mutations made via the stage are the
+              # same objects the page serialises in data_fields_updates. Else build from docs.
+              def components
+                @components ||= if @page_field_collection
+                                  ids = stage_field_ids
+                                  DataField::Collection.new(@page_field_collection.select { |f| ids.include?(f.id) })
+                                else
+                                  sections.components
+                                end
+              end
+
+              # Field ids belonging to this stage (across its sections' data/left/right fields).
+              def stage_field_ids
+                (doc['sections'] || []).flat_map do |sec|
+                  (sec['dataFields'] || []) + (sec['leftDataFields'] || []) + (sec['rightDataFields'] || [])
+                end.map { |f| f['id'] }.compact
+              end
+
+              # Hash-style access to raw doc — for backwards-compatible scripts.
+              def [](key)
+                doc[key.to_s]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +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