cocina_display 0.4.0 → 0.6.0

data/lib/cocina_display/concerns/forms.rb

@@ -0,0 +1,134 @@
+require "active_support/core_ext/enumerable"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for extracting format/genre information from a Cocina object
+    module Forms
+      # Resource types of the object, expressed in SearchWorks controlled vocabulary.
+      # @return [Array<String>]
+      def resource_types
+        mapped_values = resource_type_values.flat_map { |resource_type| searchworks_resource_type(resource_type) }
+        mapped_values << "Dataset" if dataset?
+        mapped_values.uniq
+      end
+
+      # Physical or digital forms of the object.
+      # @return [Array<String>]
+      # @example GIS dataset (nz187ct8959)
+      #   record.forms #=> ["map", "optical disc", "electronic resource"]
+      def forms
+        path("$.description.form..[?@.type == 'form'].value").uniq
+      end
+
+      # Extent of the object, such as "1 audiotape" or "1 map".
+      # @return [Array<String>]
+      # @example Oral history interview (sw705fr7011)
+      #   record.extents #=> ["1 audiotape", "1 transcript"]
+      def extents
+        path("$.description.form..[?@.type == 'extent'].value").uniq
+      end
+
+      # Genres of the object, capitalized for display.
+      # @return [Array<String>]
+      # @example GIS dataset (nz187ct8959)
+      #   record.genres #=> ["Cartographic dataset", "Geospatial data", "Geographic information systems data"]
+      def genres
+        path("$.description.form..[?@.type == 'genre'].value").map(&:upcase_first).uniq
+      end
+
+      # Genres of the object, with additional values added for search/faceting.
+      # @note These values are added for discovery in SearchWorks but not for display.
+      # @return [Array<String>]
+      def genres_search
+        genres.tap do |values|
+          values << "Thesis/Dissertation" if values.include?("Thesis")
+          values << "Conference proceedings" if values.include?("Conference publication")
+          values << "Government document" if values.include?("Government publication")
+        end.uniq
+      end
+
+      # Is the object a periodical or serial?
+      # @return [Boolean]
+      def periodical?
+        issuance_terms.include?("periodical") || issuance_terms.include?("serial") || frequency.any?
+      end
+
+      # Is the object a cartographic resource?
+      # @return [Boolean]
+      def cartographic?
+        resource_type_values.include?("cartographic")
+      end
+
+      # Is the object a web archive?
+      # @return [Boolean]
+      def archived_website?
+        genres.include?("Archived website")
+      end
+
+      # Is the object a dataset?
+      # @return [Boolean]
+      def dataset?
+        genres.include?("Dataset")
+      end
+
+      private
+
+      # Map a resource type to SearchWorks format value(s).
+      # @param resource_type [String] The resource type to map.
+      # @return [Array<String>]
+      def searchworks_resource_type(resource_type)
+        values = []
+
+        case resource_type
+        when "cartographic"
+          values << "Map"
+        when "manuscript", "mixed material"
+          values << "Archive/Manuscript"
+        when "moving image"
+          values << "Video"
+        when "notated music"
+          values << "Music score"
+        when "software, multimedia"
+          # Prevent GIS datasets from being labeled as "Software"
+          values << "Software/Multimedia" unless cartographic? || dataset?
+        when "sound recording-musical"
+          values << "Music recording"
+        when "sound recording-nonmusical", "sound recording"
+          values << "Sound recording"
+        when "still image"
+          values << "Image"
+        when "text"
+          # Can potentially map to periodical AND website if both are true. Only
+          # 2 records currently (2025) in Searchworks do this, but it is real.
+          if periodical? || archived_website?
+            values << "Journal/Periodical" if periodical?
+            values << "Archived website" if archived_website?
+          else
+            values << "Book"
+          end
+        when "three dimensional object"
+          values << "Object"
+        end
+
+        values.compact_blank
+      end
+
+      # Issuance terms for a work, drawn from the event notes.
+      # @return [Array<String>]
+      def issuance_terms
+        path("$.description.event.*.note[?@.type == 'issuance'].value").map(&:downcase).uniq
+      end
+
+      # Frequency terms for a periodical, drawn from the event notes.
+      # @return [Array<String>]
+      def frequency
+        path("$.description.event.*.note[?@.type == 'frequency'].value").map(&:downcase).uniq
+      end
+
+      # Values of the resource type form field prior to mapping.
+      def resource_type_values
+        path("$.description.form..[?@.type == 'resource type'].value").uniq
+      end
+    end
+  end
+end

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,91 @@
+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
+
+      # Combination of all subject values for searching.
+      # @see #subject_topics_other
+      # @see #subject_temporal_genre
+      # @return [Array<String>]
+      def subject_all
+        subject_topics_other + subject_temporal_genre
+      end
+
+      # Combination of topic, occupation, name, and title subject values for searching.
+      # @see #subject_topics
+      # @see #subject_other
+      # @return [Array<String>]
+      def subject_topics_other
+        subject_topics + subject_other
+      end
+
+      # Combination of occupation, name, and title subject values for searching.
+      # @see #subject_occupations
+      # @see #subject_names
+      # @see #subject_titles
+      # @return [Array<String>]
+      def subject_other
+        subject_occupations + subject_names + subject_titles
+      end
+
+      # Combination of temporal and genre subject values for searching.
+      # @see #subject_temporal
+      # @see #subject_genres
+      # @return [Array<String>]
+      def subject_temporal_genre
+        subject_temporal + subject_genres
+      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

@@ -5,6 +5,7 @@ require "active_support/core_ext/object/blank"
 require "active_support/core_ext/array/conversions"
 
 require_relative "utils"
+require_relative "marc_relator_codes"
 
 module CocinaDisplay
   # A contributor to a work, such as an author or publisher.
@@ -51,7 +52,13 @@ module CocinaDisplay
     # Does this contributor have a role that indicates they are an author?
     # @return [Boolean]
     def author?
-      roles.any? { |role| role["value"] =~ /(author|creator)/i }
+      roles.any?(&:author?)
+    end
+
+    # Does this contributor have a role that indicates they are a publisher?
+    # @return [Boolean]
+    def publisher?
+      roles.any?(&:publisher?)
     end
 
     # Does this contributor have any roles defined?
@@ -72,11 +79,9 @@ module CocinaDisplay
     # If there are multiple roles, they are joined with commas.
     # @return [String]
     def display_role
-      roles.map { |role| role["value"] }.to_sentence
+      roles.map(&:display_str).to_sentence
     end
 
-    private
-
     # All names in the Cocina as Name objects.
     # @return [Array<Name>]
     def names
@@ -86,7 +91,7 @@ module CocinaDisplay
     # All roles in the Cocina structured data.
     # @return [Array<Hash>]
     def roles
-      Array(cocina["role"])
+      @roles ||= Array(cocina["role"]).map { |role| Role.new(role) }
     end
 
     # A name associated with a contributor.
@@ -100,6 +105,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 +116,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 +129,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,12 +179,56 @@ 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"]
         end.compact_blank
       end
     end
+
+    # A role associated with a contributor.
+    class Role
+      attr_reader :cocina
+
+      # Initialize a Role object with Cocina structured data.
+      # @param cocina [Hash] The Cocina structured data for the role.
+      def initialize(cocina)
+        @cocina = cocina
+      end
+
+      # The name of the role.
+      # Translates the MARC relator code if no value was present.
+      # @return [String, nil]
+      def display_str
+        cocina["value"] || (MARC_RELATOR[code] if marc_relator?)
+      end
+
+      # A code associated with the role, e.g. a MARC relator code.
+      # @return [String, nil]
+      def code
+        cocina["code"]
+      end
+
+      # Does this role indicate the contributor is an author?
+      # @return [Boolean]
+      def author?
+        display_str =~ /^(author|creator)/i
+      end
+
+      # Does this role indicate the contributor is a publisher?
+      # @return [Boolean]
+      def publisher?
+        display_str =~ /^publisher/i
+      end
+
+      private
+
+      # Does this role have a MARC relator code?
+      # @return [Boolean]
+      def marc_relator?
+        cocina.dig("source", "code") == "marcrelator"
+      end
+    end
   end
 end

data/lib/cocina_display/dates/date.rb

@@ -82,9 +82,14 @@ module CocinaDisplay
 
       attr_reader :cocina, :date
 
+      # The type of this date, if any, such as "creation", "publication", etc.
+      # @return [String, nil]
+      attr_accessor :type
+
       def initialize(cocina)
         @cocina = cocina
         @date = self.class.parse_date(cocina["value"])
+        @type = cocina["type"] unless ["start", "end"].include?(cocina["type"])
       end
 
       # Compare this date to another {Date} or {DateRange} using its {sort_key}.
@@ -98,12 +103,6 @@ module CocinaDisplay
         cocina["value"]
       end
 
-      # The type of this date, if any, such as "creation", "publication", etc.
-      # @return [String, nil]
-      def type
-        cocina["type"]
-      end
-
       # The qualifier for this date, if any, such as "approximate", "inferred", etc.
       # @return [String, nil]
       def qualifier
@@ -132,14 +131,16 @@ module CocinaDisplay
 
       # Is this the start date in a range?
       # @return [Boolean]
+      # @note The Cocina will mark start dates with "type": "start".
       def start?
-        type == "start"
+        cocina["type"] == "start"
       end
 
       # Is this the end date in a range?
       # @return [Boolean]
+      # @note The Cocina will mark end dates with "type": "end".
       def end?
-        type == "end"
+        cocina["type"] == "end"
       end
 
       # Was the date marked as approximate?

data/lib/cocina_display/dates/date_range.rb

@@ -30,6 +30,7 @@ module CocinaDisplay
         @cocina = cocina
         @start = start
         @stop = stop
+        @type = cocina["type"]
       end
 
       # The values of the start and stop dates as an array.
@@ -83,6 +84,13 @@ module CocinaDisplay
         start&.parsed_date? || stop&.parsed_date? || false
       end
 
+      # False if both dates in the range have a known unparsable value like "9999".
+      # @see CocinaDisplay::Date#parsable?
+      # @return [Boolean]
+      def parsable?
+        start&.parsable? || stop&.parsable? || false
+      end
+
       # Decoded version of the range, if it was encoded. Strips leading zeroes.
       # @see CocinaDisplay::Date#decoded_value
       # @return [String]

data/lib/cocina_display/events/event.rb

@@ -0,0 +1,78 @@
+require_relative "location"
+require_relative "../dates/date"
+require_relative "../contributor"
+
+module CocinaDisplay
+  module Events
+    # An event associated with an object, like publication.
+    class Event
+      attr_reader :cocina
+
+      # Initialize the event with Cocina event data.
+      # @param cocina [Hash] Cocina structured data for a single event
+      def initialize(cocina)
+        @cocina = cocina
+      end
+
+      # The declared type of the event, like "publication" or "creation".
+      # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#event-types
+      # @note This can differ from the contained date types.
+      # @return [String, nil]
+      def type
+        cocina["type"]
+      end
+
+      # All types of dates associated with this event.
+      # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#event-date-types
+      # @note This can differ from the top-level event type.
+      # @return [Array<String>]
+      def date_types
+        dates.map(&:type).uniq
+      end
+
+      # True if either the event type or any date type matches the given type.
+      # @param match_type [String] The type to check against
+      # @return [Boolean]
+      def has_type?(match_type)
+        [type, *date_types].compact.include?(match_type)
+      end
+
+      # True if the event or its dates have any of the provided types.
+      # @param match_types [Array<String>] The types to check against
+      # @return [Boolean]
+      def has_any_type?(*match_types)
+        match_types.any? { |type| has_type?(type) }
+      end
+
+      # All dates associated with this event.
+      # Ignores known unparsable date values like "9999".
+      # If the date is untyped, uses this event's type as the date type.
+      # @note The date types may differ from the underlying event type.
+      # @return [Array<CocinaDisplay::Dates::Date>]
+      def dates
+        @dates ||= Array(cocina["date"]).filter_map do |date|
+          CocinaDisplay::Dates::Date.from_cocina(date)
+        end.filter(&:parsable?).map do |date|
+          date.type ||= type
+          date
+        end
+      end
+
+      # All contributors associated with this event.
+      # @return [Array<CocinaDisplay::Contributor>]
+      def contributors
+        @contributors ||= Array(cocina["contributor"]).map do |contributor|
+          CocinaDisplay::Contributor.new(contributor)
+        end
+      end
+
+      # All locations associated with this event.
+      # @return [Array<CocinaDisplay::Events::Location>]
+      def locations
+        @locations ||= Array(cocina["location"]).map do |location|
+          CocinaDisplay::Events::Location.new(location)
+        end
+      end
+    end
+  end
+end

data/lib/cocina_display/events/imprint.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "edtf"
+require "active_support"
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/object/blank"
+
+require_relative "event"
+require_relative "../utils"
+require_relative "../marc_country_codes"
+require_relative "../dates/date"
+require_relative "../dates/date_range"
+
+module CocinaDisplay
+  module Events
+    # Wrapper for Cocina events used to generate an imprint statement for display.
+    class Imprint < Event
+      # The entire imprint statement formatted as a string for display.
+      # @return [String]
+      def display_str
+        place_pub = Utils.compact_and_join([place_str, publisher_str], delimiter: " : ")
+        edition_place_pub = Utils.compact_and_join([edition_str, place_pub], delimiter: " - ")
+        Utils.compact_and_join([edition_place_pub, date_str], delimiter: ", ")
+      end
+
+      # Were any of the dates encoded?
+      # Used to detect which event(s) most likely represent the actual imprint(s).
+      def date_encoding?
+        dates.any?(&:encoding?)
+      end
+
+      private
+
+      # The date portion of the imprint statement, comprising all unique dates.
+      # @return [String]
+      def date_str
+        Utils.compact_and_join(unique_dates_for_display.map(&:qualified_value))
+      end
+
+      # The editions portion of the imprint statement, combining all edition notes.
+      # @return [String]
+      def edition_str
+        Utils.compact_and_join(Janeway.enum_for("$.note[?@.type == 'edition'].value", cocina))
+      end
+
+      # The place of publication, combining all location values.
+      # @return [String]
+      def place_str
+        Utils.compact_and_join(locations_for_display, delimiter: " : ")
+      end
+
+      # The publisher information, combining all name values for publishers.
+      # @return [String]
+      def publisher_str
+        Utils.compact_and_join(publishers.map(&:display_name), delimiter: " : ")
+      end
+
+      # All publishers associated with this imprint.
+      # @return [Array<CocinaDisplay::Contributor>]
+      # @see CocinaDisplay::Contributor#publisher?
+      def publishers
+        contributors.filter(&:publisher?)
+      end
+
+      # Filter dates for uniqueness using base value according to predefined rules.
+      # 1. For a group of dates with the same base value, choose a single one
+      # 2. Prefer unencoded dates over encoded ones when choosing a single date
+      # 3. Remove date ranges that duplicate any unencoded non-range dates
+      # @return [Array<CocinaDisplay::Dates::Date>]
+      # @see CocinaDisplay::Dates::Date#base_value
+      # @see https://consul.stanford.edu/display/chimera/MODS+display+rules#MODSdisplayrules-3b.%3CoriginInfo%3E
+      def unique_dates_for_display
+        # Choose a single date for each group with the same base value
+        deduped_dates = dates.group_by(&:base_value).map do |base_value, group|
+          if (unencoded = group.reject(&:encoding?)).any?
+            unencoded.first
+          else
+            group.first
+          end
+        end
+
+        # Remove any ranges that duplicate part of an unencoded non-range date
+        ranges, singles = deduped_dates.partition { |date| date.is_a?(CocinaDisplay::Dates::DateRange) }
+        unencoded_singles_dates = singles.reject(&:encoding?).flat_map(&:to_a)
+        ranges.reject! { |range| unencoded_singles_dates.any? { |date| range.as_interval.include?(date) } }
+
+        (singles + ranges).sort
+      end
+
+      # Filter locations to display according to predefined rules.
+      # 1. Prefer unencoded locations (plain value) over encoded ones
+      # 2. If no unencoded locations but there are MARC country codes, decode them
+      # 3. Keep only unique locations after decoding
+      def locations_for_display
+        unencoded_locs, encoded_locs = locations.partition { |loc| loc.unencoded_value? }
+        locs_for_display = unencoded_locs.presence || encoded_locs
+        locs_for_display.map(&:display_str).compact_blank.uniq
+      end
+    end
+  end
+end