cocina_display 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0724f307088c9cdd9348af463e3c659811eef65d0f1f04e094b4c664a36cfed1
-  data.tar.gz: 4b49472d07a085455ca72204e6ebde3cfc27c634f8ba9cd5b2c2a47d62d19aad
+  metadata.gz: 5662a1512975323d0324c31021fcef9cd4ff337ea8acfb5f6a3352d4abf0e303
+  data.tar.gz: fe0444d5c104e393718a996260346f98691f2e84585483bb7a2062acab347bfb
 SHA512:
-  metadata.gz: edc1e8977792d21fd6fef292f486c11eab4011dc63c854af1217aced6930ea55538e158abc261491c08b1f8492c374c52102b44931849b2350e1dacf54310d41
-  data.tar.gz: 664691764d4a4ff7da024af64ce9dd2d0841d8c014ee9439c3ebebe4b3a4c2e585e7f608f2ff943a04586dfaad8fc4ec7cfa714fade929ca9b0278ec740bff8b
+  metadata.gz: 8ff64dadfe8b2492f23d38bcc320e8de4bc6100af09adfd93d25df0aeb84c91585072dbcbb6cafc297bd503d773ee7b6bf35281fdda1d573e65f94fcb866a5a0
+  data.tar.gz: 29c42ee65d59dbac907159435f8c9924742cc4d598e656a787dee8cbfceaab8231f2bbf8cb87d14ee180ed586fc51b4d498e8009b6fd5442442d8b0932ebd30d

data/lib/cocina_display/cocina_record.rb

@@ -11,6 +11,8 @@ require_relative "concerns/events"
 require_relative "concerns/contributors"
 require_relative "concerns/identifiers"
 require_relative "concerns/titles"
+require_relative "concerns/access"
+require_relative "concerns/subjects"
 
 module CocinaDisplay
   # Public Cocina metadata for an SDR object, as fetched from PURL.
@@ -19,6 +21,8 @@ module CocinaDisplay
     include CocinaDisplay::Concerns::Contributors
     include CocinaDisplay::Concerns::Identifiers
     include CocinaDisplay::Concerns::Titles
+    include CocinaDisplay::Concerns::Access
+    include CocinaDisplay::Concerns::Subjects
 
     # Fetch a public Cocina document from PURL and create a CocinaRecord.
     # @note This is intended to be used in development or testing only.
@@ -73,6 +77,13 @@ module CocinaDisplay
       cocina_doc["type"].split("/").last
     end
 
+    # Primary processing label for the object.
+    # @note This may or may not be the same as the title.
+    # @return [String, nil]
+    def label
+      cocina_doc["label"]
+    end
+
     # True if the object is a collection.
     # @return [Boolean]
     def collection?
@@ -90,70 +101,5 @@ module CocinaDisplay
     def files
       path("$.structural.contains[*].structural.contains[*]")
     end
-
-    # The PURL URL for this object.
-    # @return [String]
-    # @example
-    #  record.purl_url #=> "https://purl.stanford.edu/bx658jh7339"
-    def purl_url
-      cocina_doc.dig("description", "purl") || "https://purl.stanford.edu/#{bare_druid}"
-    end
-
-    # The URL to the PURL environment this object is from.
-    # @note Objects accessed via UAT will still have a production PURL base URL.
-    # @return [String]
-    # @example
-    #   record.purl_base_url #=> "https://purl.stanford.edu"
-    def purl_base_url
-      URI(purl_url).origin
-    end
-
-    # The URL to the stacks environment this object is shelved in.
-    # Corresponds to the PURL environment.
-    # @see purl_base_url
-    # @return [String]
-    # @example
-    #  record.stacks_base_url #=> "https://stacks.stanford.edu"
-    def stacks_base_url
-      if purl_base_url == "https://sul-purl-stage.stanford.edu"
-        "https://sul-stacks-stage.stanford.edu"
-      else
-        "https://stacks.stanford.edu"
-      end
-    end
-
-    # The oEmbed URL for the object, optionally with additional parameters.
-    # Corresponds to the PURL environment.
-    # @param params [Hash] Additional parameters to include in the oEmbed URL.
-    # @return [String]
-    # @return [nil] if the object is a collection.
-    # @example Generate an oEmbed URL for the viewer and hide the title
-    #   record.oembed_url(hide_title: true) #=> "https://purl.stanford.edu/bx658jh7339/embed.json?hide_title=true"
-    def oembed_url(params: {})
-      return if collection?
-
-      params[:url] ||= purl_url
-      "#{purl_base_url}/embed.json?#{params.to_query}"
-    end
-
-    # The download URL to get the entire object as a .zip file.
-    # Stacks generates the .zip for the object on request.
-    # @return [String]
-    # @example
-    #   record.download_url #=> "https://stacks.stanford.edu/object/bx658jh7339"
-    def download_url
-      "#{stacks_base_url}/object/#{bare_druid}"
-    end
-
-    # The IIIF manifest URL for the object.
-    # PURL generates the IIIF manifest.
-    # @param version [Integer] The IIIF presentation spec version to use (3 or 2).
-    # @return [String]
-    # @example
-    #  record.iiif_manifest_url #=> "https://purl.stanford.edu/bx658jh7339/iiif3/manifest"
-    def iiif_manifest_url(version: 3)
-      iiif_path = (version == 3) ? "iiif3" : "iiif"
-      "#{purl_url}/#{iiif_path}/manifest"
-    end
   end
 end

data/lib/cocina_display/concerns/access.rb

@@ -0,0 +1,71 @@
+module CocinaDisplay
+  module Concerns
+    # Methods that generate URLs to access an object.
+    module Access
+      # The PURL URL for this object.
+      # @return [String]
+      # @example
+      #  record.purl_url #=> "https://purl.stanford.edu/bx658jh7339"
+      def purl_url
+        cocina_doc.dig("description", "purl") || "https://purl.stanford.edu/#{bare_druid}"
+      end
+
+      # The URL to the PURL environment this object is from.
+      # @note Objects accessed via UAT will still have a production PURL base URL.
+      # @return [String]
+      # @example
+      #   record.purl_base_url #=> "https://purl.stanford.edu"
+      def purl_base_url
+        URI(purl_url).origin
+      end
+
+      # The URL to the stacks environment this object is shelved in.
+      # Corresponds to the PURL environment.
+      # @see purl_base_url
+      # @return [String]
+      # @example
+      #  record.stacks_base_url #=> "https://stacks.stanford.edu"
+      def stacks_base_url
+        if purl_base_url == "https://sul-purl-stage.stanford.edu"
+          "https://sul-stacks-stage.stanford.edu"
+        else
+          "https://stacks.stanford.edu"
+        end
+      end
+
+      # The oEmbed URL for the object, optionally with additional parameters.
+      # Corresponds to the PURL environment.
+      # @param params [Hash] Additional parameters to include in the oEmbed URL.
+      # @return [String]
+      # @return [nil] if the object is a collection.
+      # @example Generate an oEmbed URL for the viewer and hide the title
+      #   record.oembed_url(hide_title: true) #=> "https://purl.stanford.edu/bx658jh7339/embed.json?hide_title=true"
+      def oembed_url(params: {})
+        return if collection?
+
+        params[:url] ||= purl_url
+        "#{purl_base_url}/embed.json?#{params.to_query}"
+      end
+
+      # The download URL to get the entire object as a .zip file.
+      # Stacks generates the .zip for the object on request.
+      # @return [String]
+      # @example
+      #   record.download_url #=> "https://stacks.stanford.edu/object/bx658jh7339"
+      def download_url
+        "#{stacks_base_url}/object/#{bare_druid}"
+      end
+
+      # The IIIF manifest URL for the object.
+      # PURL generates the IIIF manifest.
+      # @param version [Integer] The IIIF presentation spec version to use (3 or 2).
+      # @return [String]
+      # @example
+      #  record.iiif_manifest_url #=> "https://purl.stanford.edu/bx658jh7339/iiif3/manifest"
+      def iiif_manifest_url(version: 3)
+        iiif_path = (version == 3) ? "iiif3" : "iiif"
+        "#{purl_url}/#{iiif_path}/manifest"
+      end
+    end
+  end
+end

data/lib/cocina_display/concerns/events.rb

@@ -41,6 +41,20 @@ module CocinaDisplay
         pub_date_edtf(ignore_qualified: ignore_qualified)&.year
       end
 
+      # The range of preferred publication years as an array of integers.
+      # Considers publication, creation, and capture dates in that order.
+      # Prefers dates marked as primary and those with a declared encoding.
+      # @param ignore_qualified [Boolean] Reject qualified dates (e.g. approximate)
+      # @return [Array<Integer>, nil]
+      # @note 6 BCE will appear as -5; 4 CE will appear as 4.
+      def pub_year_int_range(ignore_qualified: false)
+        date = pub_date(ignore_qualified: ignore_qualified)
+        return unless date
+
+        date = date.as_interval if date.is_a? CocinaDisplay::Dates::DateRange
+        date.to_a.map(&:year).compact.uniq.sort
+      end
+
       # String for displaying the earliest preferred publication year or range.
       # Considers publication, creation, and capture dates in that order.
       # Prefers dates marked as primary and those with a declared encoding.

data/lib/cocina_display/concerns/identifiers.rb

@@ -40,11 +40,19 @@ module CocinaDisplay
 
       # The HRID of the item in FOLIO, if defined.
       # @note This doesn't imply the object is available in Searchworks at this ID.
+      # @param [refresh] [Boolean] Filter to links with refresh set to this value.
       # @return [String, nil]
-      # @example
+      # @example With a link regardless of refresh:
       #   record.folio_hrid #=> "a12845814"
-      def folio_hrid
-        path("$.identification.catalogLinks[?(@.catalog == 'folio')].catalogRecordId").first
+      # @example With a link that is not refreshed:
+      #   record.folio_hrid(refresh: true) #=> nil
+      def folio_hrid(refresh: nil)
+        link = path("$.identification.catalogLinks[?(@.catalog == 'folio')]").first
+        hrid = link&.dig("catalogRecordId")
+        return if hrid.blank?
+        return hrid if refresh.nil?
+
+        (link["refresh"] == refresh) ? hrid : nil
       end
 
       # The FOLIO HRID if defined, otherwise the bare DRUID.

data/lib/cocina_display/concerns/subjects.rb

@@ -0,0 +1,58 @@
+require_relative "../subject"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for extracting and formatting subject information.
+    module Subjects
+      # All unique subjects that are topics, formatted as strings for display.
+      # @return [Array<String>]
+      def subject_topics
+        subjects.filter { |s| s.type == "topic" }.map(&:display_str).uniq
+      end
+
+      # All unique subjects that are genres, formatted as strings for display.
+      # @return [Array<String>]
+      def subject_genres
+        subjects.filter { |s| s.type == "genre" }.map(&:display_str).uniq
+      end
+
+      # All unique subjects that are titles, formatted as strings for display.
+      # @return [Array<String>]
+      def subject_titles
+        subjects.filter { |s| s.type == "title" }.map(&:display_str).uniq
+      end
+
+      # All unique subjects that are date/time info, formatted as strings for display.
+      # @return [Array<String>]
+      def subject_temporal
+        subjects.filter { |s| s.type == "time" }.map(&:display_str).uniq
+      end
+
+      # All unique subjects that are occupations, formatted as strings for display.
+      # @return [Array<String>]
+      def subject_occupations
+        subjects.filter { |s| s.type == "occupation" }.map(&:display_str).uniq
+      end
+
+      # All unique subjects that are names of entities, formatted as strings for display.
+      # @note Multiple types are handled: person, family, organization, conference, etc.
+      # @see CocinaDisplay::NameSubject
+      # @return [Array<String>]
+      def subject_names
+        subjects.filter { |s| s.is_a? NameSubject }.map(&:display_str).uniq
+      end
+
+      private
+
+      # All subjects, accessible as Subject objects.
+      # Checks both description.subject and description.geographic.subject.
+      # @return [Array<Subject>]
+      def subjects
+        @subjects ||= Enumerator::Chain.new(
+          path("$.description.subject[*]"),
+          path("$.description.geographic[*].subject[*]")
+        ).map { |s| Subject.from_cocina(s) }
+      end
+    end
+  end
+end

data/lib/cocina_display/contributor.rb

@@ -100,6 +100,10 @@ module CocinaDisplay
       end
 
       # The display string for the name, optionally including life dates.
+      # Uses these values in order, if present:
+      # 1. Unstructured value
+      # 2. Any structured/parallel values marked as "display"
+      # 3. Joined structured values, optionally with life dates
       # @param with_date [Boolean] Include life dates, if present
       # @return [String]
       # @example no dates
@@ -107,7 +111,11 @@ module CocinaDisplay
       # @example with dates
       #   name.display_name(with_date: true) # => "King, Martin Luther, Jr., 1929-1968"
       def display_str(with_date: false)
-        if dates_str.present? && with_date
+        if cocina["value"].present?
+          cocina["value"]
+        elsif display_name_str.present?
+          display_name_str
+        elsif dates_str.present? && with_date
           Utils.compact_and_join([full_name_str, dates_str], delimiter: ", ")
         else
           full_name_str
@@ -116,12 +124,10 @@ module CocinaDisplay
 
       private
 
-      # The full name as a string.
-      # If any names were marked as "display", prefer those.
-      # Otherwise, combine all name components.
+      # The full name as a string, combining all name components.
       # @return [String]
       def full_name_str
-        display_name_str.presence || Utils.compact_and_join(name_components, delimiter: ", ")
+        Utils.compact_and_join(name_components, delimiter: ", ")
       end
 
       # Flattened form of any names explicitly marked as "display name".
@@ -168,7 +174,7 @@ module CocinaDisplay
       # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#contributor-name-part-types-for-structured-value
       # @note Currently we do nothing with "alternative", "inverted full name", "pseudonym", and "transliteration" types.
       def name_values
-        Utils.flatten_structured_values(cocina).each_with_object({}) do |node, hash|
+        Utils.flatten_nested_values(cocina).each_with_object({}) do |node, hash|
           type = node["type"] || "name"
           hash[type] ||= []
           hash[type] << node["value"]

data/lib/cocina_display/subject.rb

@@ -0,0 +1,127 @@
+require_relative "utils"
+require_relative "contributor"
+require_relative "title_builder"
+require_relative "dates/date"
+
+module CocinaDisplay
+  # Base class for subjects in Cocina structured data.
+  class Subject
+    attr_reader :cocina
+
+    # Extract the type of the subject from the Cocina structured data.
+    # If no top-level type, uses the first structuredValue type.
+    # @param cocina [Hash] The Cocina structured data for the subject.
+    # @return [String, nil] The type of the subject, or nil if none
+    # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#subject-types
+    def self.detect_type(cocina)
+      cocina["type"] || Utils.flatten_nested_values(cocina).pick("type")
+    end
+
+    # Choose and create the appropriate Subject subclass based on type.
+    # @param cocina [Hash] The Cocina structured data for the subject.
+    # @return [Subject]
+    # @see detect_type
+    def self.from_cocina(cocina)
+      case detect_type(cocina)
+      when "person", "family", "organization", "conference", "event", "name"
+        NameSubject.new(cocina)
+      when "title"
+        TitleSubject.new(cocina)
+      when "time"
+        TemporalSubject.new(cocina)
+      # TODO: special handling for geospatial subjects
+      # when "map coordinates", "bounding box coordinates", "point coordinates"
+      else
+        Subject.new(cocina)
+      end
+    end
+
+    # Initialize a Subject object with Cocina structured data.
+    # @param cocina [Hash] The Cocina structured data for the subject.
+    def initialize(cocina)
+      @cocina = cocina
+    end
+
+    # The type of the subject.
+    # If no top-level type, uses the first structuredValue type.
+    # @return [String, nil] The type of the subject, or nil if none
+    # @see detect_type
+    def type
+      self.class.detect_type(cocina)
+    end
+
+    # A string representation of the subject, formatted for display.
+    # Concatenates any structured values with an appropriate delimiter.
+    # Subclasses may override this for more specific formatting.
+    # @return [String]
+    def display_str
+      Utils.compact_and_join(descriptive_values, delimiter: delimiter)
+    end
+
+    private
+
+    # Flatten any structured values into an array of Hashes with "value" keys.
+    # If no structured values, will return the top-level cocina data.
+    # @see Utils.flatten_nested_values
+    # @return [Array<Hash>] An array of Hashes representing all values.
+    def descriptive_values
+      Utils.flatten_nested_values(cocina).pluck("value")
+    end
+
+    # Delimiter to use for joining structured subject values.
+    # LCSH uses a comma (the default); catalog headings use " > ".
+    # @return [String]
+    def delimiter
+      if cocina["displayLabel"]&.downcase == "catalog heading"
+        " > "
+      else
+        ", "
+      end
+    end
+  end
+
+  # A subject representing a named entity.
+  class NameSubject < Subject
+    attr_reader :name
+
+    # Initialize a NameSubject object with Cocina structured data.
+    # @param cocina [Hash] The Cocina structured data for the subject.
+    def initialize(cocina)
+      super
+      @name = Contributor::Name.new(cocina)
+    end
+
+    # Use the contributor name formatting rules for display.
+    # @return [String] The formatted name string, including life dates
+    # @see CocinaDisplay::Contributor::Name#display_str
+    def display_str
+      @name.display_str(with_date: true)
+    end
+  end
+
+  # A subject representing an entity with a title.
+  class TitleSubject < Subject
+    # Construct a title string to use for display.
+    # @see CocinaDisplay::TitleBuilder.build
+    # @note Unclear how often structured title subjects occur "in the wild".
+    # @return [String]
+    def display_str
+      TitleBuilder.build([cocina])
+    end
+  end
+
+  # A subject representing a date and/or time.
+  class TemporalSubject < Subject
+    attr_reader :date
+
+    def initialize(cocina)
+      super
+      @date = Dates::Date.from_cocina(cocina)
+    end
+
+    # @return [String] The formatted date/time string for display
+    def display_str
+      @date.qualified_value
+    end
+  end
+end

data/lib/cocina_display/utils.rb

@@ -19,15 +19,31 @@ module CocinaDisplay
       end.delete_suffix(delimiter)
     end
 
-    # Recursively flatten structured values in Cocina metadata.
-    # Returns a list of hashes representing the "leaf" nodes with values.
+    # Recursively flatten structured and parallel values in Cocina metadata.
+    # Returns a list of hashes representing the "leaf" nodes with +value+ key.
     # @return [Array<Hash>] List of node hashes with "value" present
-    def self.flatten_structured_values(cocina, output = [])
+    # @param cocina [Hash] The Cocina structured data to flatten
+    # @param output [Array] Used for recursion, should be empty on first call
+    # @example simple value
+    #  cocina = { "value" => "John Doe", "type" => "name" }
+    #  Utils.flatten_nested_values(cocina)
+    #  #=> [{"value" => "John Doe", "type" => "name"}]
+    # @example structured values
+    #  cocina = { "structuredValue" => [{"value" => "foo"},  {"value" => "bar"}] }
+    #  Utils.flatten_nested_values(cocina)
+    #  #=> [{"value" => "foo"}, {"value" => "bar"}]
+    # @example parallel structured and simple values
+    #  cocina = { "parallelValue" => [{"value" => "foo" }, { "structuredValue" => [{"value" => "bar"},  {"value" => "baz"}] }] }
+    #  Utils.flatten_nested_values(cocina)
+    #  #=> [{"value" => "foo"}, {"value" => "foo"}, {"value" => "baz"}]
+    def self.flatten_nested_values(cocina, output = [])
       return [cocina] if cocina["value"].present?
-      return cocina.flat_map { |node| flatten_structured_values(node, output) } if cocina.is_a?(Array)
-      return output unless (structured_values = Array(cocina["structuredValue"])).present?
+      return cocina.flat_map { |node| flatten_nested_values(node, output) } if cocina.is_a?(Array)
 
-      structured_values.flat_map { |node| flatten_structured_values(node, output) }
+      nested_values = Array(cocina["structuredValue"]) + Array(cocina["parallelValue"])
+      return output unless nested_values.any?
+
+      nested_values.flat_map { |node| flatten_nested_values(node, output) }
     end
   end
 end

data/lib/cocina_display/version.rb

@@ -2,5 +2,5 @@
 
 # :nodoc:
 module CocinaDisplay
-  VERSION = "0.4.0" # :nodoc:
+  VERSION = "0.5.0" # :nodoc:
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cocina_display
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nick Budak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-09 00:00:00.000000000 Z
+date: 2025-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: janeway-jsonpath
@@ -28,22 +28,16 @@ dependencies:
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.2
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.2
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: edtf
   requirement: !ruby/object:Gem::Requirement
@@ -176,15 +170,18 @@ files:
 - Rakefile
 - lib/cocina_display.rb
 - lib/cocina_display/cocina_record.rb
+- lib/cocina_display/concerns/access.rb
 - lib/cocina_display/concerns/contributors.rb
 - lib/cocina_display/concerns/events.rb
 - lib/cocina_display/concerns/identifiers.rb
+- lib/cocina_display/concerns/subjects.rb
 - lib/cocina_display/concerns/titles.rb
 - lib/cocina_display/contributor.rb
 - lib/cocina_display/dates/date.rb
 - lib/cocina_display/dates/date_range.rb
 - lib/cocina_display/imprint.rb
 - lib/cocina_display/marc_country_codes.rb
+- lib/cocina_display/subject.rb
 - lib/cocina_display/title_builder.rb
 - lib/cocina_display/utils.rb
 - lib/cocina_display/version.rb