cocina_display 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ef43e2d573c99c10d6db87974ff32091ff7e7d312bf2e812ef1043f513f291c
-  data.tar.gz: f04b35117201aaebff5e8d041d2776525dcd18a46bc408baf9d8649376d90618
+  metadata.gz: 5662a1512975323d0324c31021fcef9cd4ff337ea8acfb5f6a3352d4abf0e303
+  data.tar.gz: fe0444d5c104e393718a996260346f98691f2e84585483bb7a2062acab347bfb
 SHA512:
-  metadata.gz: c36dd129d129ce44c7c516b670295b59f68732d0270664dda63ce119fe37ec60e68c6fd615e37ada5ecef06777db7be30cd708d0f0c461c18c97085e98eb553f
-  data.tar.gz: cddd56237670d908a6be7951e24fe62a0fbd3076fd0eff96693c7debc03fa9ab8e01157a330923938143ec2067a4d97d4ead339f44fd2b00d0bcf99ea92b6af0
+  metadata.gz: 8ff64dadfe8b2492f23d38bcc320e8de4bc6100af09adfd93d25df0aeb84c91585072dbcbb6cafc297bd503d773ee7b6bf35281fdda1d573e65f94fcb866a5a0
+  data.tar.gz: 29c42ee65d59dbac907159435f8c9924742cc4d598e656a787dee8cbfceaab8231f2bbf8cb87d14ee180ed586fc51b4d498e8009b6fd5442442d8b0932ebd30d

data/README.md

@@ -40,7 +40,7 @@ There is also a helper method to fetch the Cocina JSON for a given DRUID and imm
 The `CocinaRecord` class provides some methods to access common fields, as well as an underlying hash representation parsed from the JSON.
 
 ```ruby
-> record.title
+> record.main_title
 => "Bugatti Type 51A. Road & Track Salon January 1957"
 > record.content_type
 => "image"

data/lib/cocina_display/cocina_record.rb

@@ -7,13 +7,22 @@ require "active_support"
 require "active_support/core_ext/object/blank"
 require "active_support/core_ext/hash/conversions"
 
-require_relative "title_builder"
 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.
   class CocinaRecord
     include CocinaDisplay::Concerns::Events
+    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.
@@ -45,60 +54,6 @@ module CocinaDisplay
       Janeway.enum_for(path_expression, cocina_doc)
     end
 
-    # The DRUID for the object, with the +druid:+ prefix.
-    # @return [String]
-    # @example
-    #   record.druid #=> "druid:bb099mt5053"
-    def druid
-      cocina_doc["externalIdentifier"]
-    end
-
-    # The DRUID for the object, without the +druid:+ prefix.
-    # @return [String]
-    # @example
-    #   record.bare_druid #=> "bb099mt5053"
-    def bare_druid
-      druid.delete_prefix("druid:")
-    end
-
-    # The DOI for the object, if there is one – just the identifier part.
-    # @return [String, nil]
-    # @example
-    #   record.doi #=> "10.25740/ppax-bf07"
-    def doi
-      doi_id = path("$.identification.doi").first ||
-        path("$.description.identifier[?match(@.type, 'doi|DOI')].value").first ||
-        path("$.description.identifier[?search(@.uri, 'doi.org')].uri").first
-
-      URI(doi_id).path.delete_prefix("/") if doi_id.present?
-    end
-
-    # The DOI as a URL, if there is one. Any valid DOI should resolve via doi.org.
-    # @return [String, nil]
-    # @example
-    #   record.doi_url #=> "https://doi.org/10.25740/ppax-bf07"
-    def doi_url
-      URI.join("https://doi.org", doi).to_s if doi.present?
-    end
-
-    # The HRID of the item in FOLIO, if defined.
-    # @note This doesn't imply the object is available in Searchworks at this ID.
-    # @return [String, nil]
-    # @example
-    #   record.folio_hrid #=> "a12845814"
-    def folio_hrid
-      path("$.identification.catalogLinks[?(@.catalog == 'folio')].catalogRecordId").first
-    end
-
-    # The FOLIO HRID if defined, otherwise the bare DRUID.
-    # @note This doesn't imply the object is available in Searchworks at this ID.
-    # @see folio_hrid
-    # @see bare_druid
-    # @return [String]
-    def searchworks_id
-      folio_hrid || bare_druid
-    end
-
     # Timestamp when the Cocina was created.
     # @note This is for the metadata itself, not the object.
     # @return [Time]
@@ -122,34 +77,19 @@ 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?
       content_type == "collection"
     end
 
-    # The main title for the object.
-    # @note If you need more formatting control, consider using {CocinaDisplay::TitleBuilder} directly.
-    # @return [String]
-    # @example
-    #   record.title #=> "Bugatti Type 51A. Road & Track Salon January 1957"
-    def title
-      CocinaDisplay::TitleBuilder.build(
-        cocina_doc.dig("description", "title"),
-        catalog_links: cocina_doc.dig("identification", "catalogLinks")
-      )
-    end
-
-    # Alternative or translated titles for the object. Does not include the main title.
-    # @return [Array<String>]
-    # @example
-    #  record.additional_titles #=> ["Alternate title 1", "Alternate title 2"]
-    def additional_titles
-      CocinaDisplay::TitleBuilder.additional_titles(
-        cocina_doc.dig("description", "title")
-      )
-    end
-
     # Traverse nested FileSets and return an enumerator over their files.
     # Each file is a +Hash+.
     # @return [Enumerator] Enumerator over file hashes
@@ -161,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/contributors.rb

@@ -0,0 +1,94 @@
+require_relative "../contributor"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for finding and formatting names for contributors
+    module Contributors
+      # The main author's name, formatted for display.
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [String]
+      # @return [nil] if no main author is found
+      # @example
+      #   record.main_author #=> "Smith, John"
+      # @example with date
+      #   record.main_author(with_date: true) #=> "Smith, John, 1970-2020"
+      def main_author(with_date: false)
+        main_author_contributor&.display_name(with_date: with_date)
+      end
+
+      # All author names except the main one, formatted for display.
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [Array<String>]
+      def additional_authors(with_date: false)
+        additional_author_contributors.map { |c| c.display_name(with_date: with_date) }
+      end
+
+      # All names of authors who are people, formatted for display.
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [Array<String>]
+      def person_authors(with_date: false)
+        authors.filter(&:person?).map { |c| c.display_name(with_date: with_date) }
+      end
+
+      # All names of non-person authors, formatted for display.
+      # This includes organizations, conferences, families, etc.
+      # @return [Array<String>]
+      # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#contributor-types
+      def impersonal_authors
+        authors.reject(&:person?).map(&:display_name)
+      end
+
+      # All names of authors that are organizations, formatted for display.
+      # @return [Array<String>]
+      def organization_authors
+        authors.filter(&:organization?).map(&:display_name)
+      end
+
+      # All names of authors that are conferences, formatted for display.
+      # @return [Array<String>]
+      def conference_authors
+        authors.filter(&:conference?).map(&:display_name)
+      end
+
+      # A string value for sorting by author that sorts missing values last.
+      # Ignores punctuation and leading/trailing spaces.
+      # @return [String]
+      def sort_author
+        (main_author_contributor&.display_name || "\u{10FFFF}").gsub(/[[:punct:]]*/, "").strip
+      end
+
+      private
+
+      # All contributors for the object, including authors, editors, etc.
+      # @return [Array<Contributor>]
+      def contributors
+        @contributors ||= path("$.description.contributor[*]").map { |c| Contributor.new(c) }
+      end
+
+      # All contributors with a "creator" or "author" role.
+      # @return [Array<Contributor>]
+      # @see Contributor#author?
+      def authors
+        contributors.filter(&:author?)
+      end
+
+      # Contributor object representing the primary author.
+      # Selected according to the following rules:
+      # 1. If there is a primary author or creator, use that.
+      # 2. If there are no primary authors or creators, use the first one.
+      # 3. If there are none at all, use the first contributor without any role.
+      # @return [Contributor]
+      # @return [nil] if no suitable contributor is found
+      def main_author_contributor
+        authors.find(&:primary?).presence || authors.first || contributors.find { |c| !c.role? }.presence
+      end
+
+      # All author/creator contributors except the main one.
+      # @return [Array<Contributor>]
+      def additional_author_contributors
+        return [] if authors.empty? || authors.one? || !authors.include?(main_author_contributor)
+        authors - [main_author_contributor]
+      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

@@ -0,0 +1,68 @@
+module CocinaDisplay
+  module Concerns
+    # Methods for extracting and formatting identifiers from Cocina records.
+    module Identifiers
+      # The DRUID for the object, with the +druid:+ prefix.
+      # @return [String]
+      # @example
+      #   record.druid #=> "druid:bb099mt5053"
+      def druid
+        cocina_doc["externalIdentifier"]
+      end
+
+      # The DRUID for the object, without the +druid:+ prefix.
+      # @return [String]
+      # @example
+      #   record.bare_druid #=> "bb099mt5053"
+      def bare_druid
+        druid.delete_prefix("druid:")
+      end
+
+      # The DOI for the object, if there is one – just the identifier part.
+      # @return [String, nil]
+      # @example
+      #   record.doi #=> "10.25740/ppax-bf07"
+      def doi
+        doi_id = path("$.identification.doi").first ||
+          path("$.description.identifier[?match(@.type, 'doi|DOI')].value").first ||
+          path("$.description.identifier[?search(@.uri, 'doi.org')].uri").first
+
+        URI(doi_id).path.delete_prefix("/") if doi_id.present?
+      end
+
+      # The DOI as a URL, if there is one. Any valid DOI should resolve via doi.org.
+      # @return [String, nil]
+      # @example
+      #   record.doi_url #=> "https://doi.org/10.25740/ppax-bf07"
+      def doi_url
+        URI.join("https://doi.org", doi).to_s if doi.present?
+      end
+
+      # 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 With a link regardless of refresh:
+      #   record.folio_hrid #=> "a12845814"
+      # @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.
+      # @note This doesn't imply the object is available in Searchworks at this ID.
+      # @see folio_hrid
+      # @see bare_druid
+      # @return [String]
+      def searchworks_id
+        folio_hrid || bare_druid
+      end
+    end
+  end
+end

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/concerns/titles.rb

@@ -0,0 +1,64 @@
+require_relative "../title_builder"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for finding and formatting titles.
+    module Titles
+      # The main title for the object, without subtitle, part name, etc.
+      # If there are multiple titles, uses the first.
+      # @see CocinaDisplay::TitleBuilder#main_title
+      # @note This corresponds to the "short title" in MODS XML, or MARC 245$a only.
+      # @return [String]
+      def main_title
+        CocinaDisplay::TitleBuilder.main_title(cocina_titles).first
+      end
+
+      # The full title for the object, including subtitle, part name, etc.
+      # If there are multiple titles, uses the first.
+      # @see CocinaDisplay::TitleBuilder#full_title
+      # @note This corresponds to the entire MARC 245 field.
+      # @return [String]
+      def full_title
+        CocinaDisplay::TitleBuilder.full_title(cocina_titles, catalog_links: catalog_links).first
+      end
+
+      # The full title, joined together with additional punctuation.
+      # If there are multiple titles, uses the first.
+      # @see CocinaDisplay::TitleBuilder#build
+      # @return [String]
+      def display_title
+        CocinaDisplay::TitleBuilder.build(cocina_titles, catalog_links: catalog_links)
+      end
+
+      # Any additional titles for the object excluding the main title.
+      # @return [Array<String>]
+      # @see CocinaDisplay::TitleBuilder#additional_titles
+      def additional_titles
+        CocinaDisplay::TitleBuilder.additional_titles(cocina_titles)
+      end
+
+      # A string value for sorting by title that sorts missing values last.
+      # Ignores punctuation, leading/trailing spaces, and non-sorting characters.
+      # @see CocinaDisplay::TitleBuilder#sort_title
+      # @return [String]
+      def sort_title
+        CocinaDisplay::TitleBuilder.sort_title(cocina_titles, catalog_links: catalog_links).first || "\u{10FFFF}"
+      end
+
+      private
+
+      # The titles from the Cocina document, as an array of hashes.
+      # @return [Array<Hash>]
+      def cocina_titles
+        @cocina_titles ||= Array(cocina_doc.dig("description", "title"))
+      end
+
+      # The catalog links from the Cocina document, as an array of hashes.
+      # These link to FOLIO and can include part labels used to construct titles.
+      # @return [Array<Hash>]
+      def catalog_links
+        @catalog_links ||= Array(cocina_doc.dig("identification", "catalogLinks"))
+      end
+    end
+  end
+end

data/lib/cocina_display/contributor.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/array/conversions"
+
+require_relative "utils"
+
+module CocinaDisplay
+  # A contributor to a work, such as an author or publisher.
+  class Contributor
+    attr_reader :cocina
+
+    # Initialize a Contributor object with Cocina structured data.
+    # @param cocina [Hash] The Cocina structured data for the contributor.
+    def initialize(cocina)
+      @cocina = cocina
+    end
+
+    # String representation of the contributor, including name and role.
+    # Used for debugging and logging.
+    # @return [String]
+    def to_s
+      Utils.compact_and_join([display_name, display_role], delimiter: ": ")
+    end
+
+    # Is this contributor a human?
+    # @return [Boolean]
+    def person?
+      cocina["type"] == "person"
+    end
+
+    # Is this contributor an organization?
+    # @return [Boolean]
+    def organization?
+      cocina["type"] == "organization"
+    end
+
+    # Is this contributor a conference?
+    # @return [Boolean]
+    def conference?
+      cocina["type"] == "conference"
+    end
+
+    # Is this contributor marked as primary?
+    # @return [Boolean]
+    def primary?
+      cocina["status"] == "primary"
+    end
+
+    # Does this contributor have a role that indicates they are an author?
+    # @return [Boolean]
+    def author?
+      roles.any? { |role| role["value"] =~ /(author|creator)/i }
+    end
+
+    # Does this contributor have any roles defined?
+    # @return [Boolean]
+    def role?
+      roles.any?
+    end
+
+    # The display name for the contributor as a string.
+    # Uses the first name if multiple names are present.
+    # @param with_date [Boolean] Include life dates, if present
+    # @return [String]
+    def display_name(with_date: false)
+      names.map { |name| name.display_str(with_date: with_date) }.first
+    end
+
+    # A string representation of the contributor's roles, formatted for display.
+    # If there are multiple roles, they are joined with commas.
+    # @return [String]
+    def display_role
+      roles.map { |role| role["value"] }.to_sentence
+    end
+
+    private
+
+    # All names in the Cocina as Name objects.
+    # @return [Array<Name>]
+    def names
+      @names ||= Array(cocina["name"]).map { |name| Name.new(name) }
+    end
+
+    # All roles in the Cocina structured data.
+    # @return [Array<Hash>]
+    def roles
+      Array(cocina["role"])
+    end
+
+    # A name associated with a contributor.
+    class Name
+      attr_reader :cocina
+
+      # Initialize a Name object with Cocina structured data.
+      # @param cocina [Hash] The Cocina structured data for the name.
+      def initialize(cocina)
+        @cocina = cocina
+      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
+      #   name.display_name # => "King, Martin Luther, Jr."
+      # @example with dates
+      #   name.display_name(with_date: true) # => "King, Martin Luther, Jr., 1929-1968"
+      def display_str(with_date: false)
+        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
+        end
+      end
+
+      private
+
+      # The full name as a string, combining all name components.
+      # @return [String]
+      def full_name_str
+        Utils.compact_and_join(name_components, delimiter: ", ")
+      end
+
+      # Flattened form of any names explicitly marked as "display name".
+      # @return [String]
+      def display_name_str
+        Utils.compact_and_join(Array(name_values["display"]), delimiter: ", ")
+      end
+
+      # List of all name components.
+      # If any of forename, surname, or term of address are present, those are used.
+      # Otherwise, fall back to any names explicitly marked as "name" or untyped.
+      # @return [Array<String>]
+      def name_components
+        [surname_str, forename_ordinal_str, terms_of_address_str].compact_blank.presence || Array(name_values["name"])
+      end
+
+      # Flatten all forenames and ordinals into a single string.
+      # @return [String]
+      def forename_ordinal_str
+        Utils.compact_and_join(Array(name_values["forename"]) + Array(name_values["ordinal"]), delimiter: " ")
+      end
+
+      # Flatten all terms of address into a single string.
+      # @return [String]
+      def terms_of_address_str
+        Utils.compact_and_join(Array(name_values["term of address"]), delimiter: ", ")
+      end
+
+      # Flatten all surnames into a single string.
+      # @return [String]
+      def surname_str
+        Utils.compact_and_join(Array(name_values["surname"]), delimiter: " ")
+      end
+
+      # Flatten all life and activity dates into a single string.
+      # @return [String]
+      def dates_str
+        Utils.compact_and_join(Array(name_values["life dates"]) + Array(name_values["activity dates"]), delimiter: ", ")
+      end
+
+      # A hash mapping destructured name types to their values.
+      # Name values with no type are grouped under "name".
+      # @return [Hash<String, Array<String>>]
+      # @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_nested_values(cocina).each_with_object({}) do |node, hash|
+          type = node["type"] || "name"
+          hash[type] ||= []
+          hash[type] << node["value"]
+        end.compact_blank
+      end
+    end
+  end
+end

data/lib/cocina_display/imprint.rb

@@ -5,9 +5,10 @@ require "active_support"
 require "active_support/core_ext/enumerable"
 require "active_support/core_ext/object/blank"
 
+require_relative "utils"
+require_relative "marc_country_codes"
 require_relative "dates/date"
 require_relative "dates/date_range"
-require_relative "marc_country_codes"
 
 module CocinaDisplay
   # Wrapper for Cocina events used to generate an imprint statement for display.
@@ -20,23 +21,6 @@ module CocinaDisplay
       cocina_dates.map { |cd| CocinaDisplay::Dates::Date.from_cocina(cd) }.filter(&:parsable?).compact
     end
 
-    # Join non-empty values into a string using provided delimiter.
-    # If values already end in delimiter (ignoring whitespace), join with a space instead.
-    # @param values [Array<String>] The values to compact and join
-    # @param delimiter [String] The delimiter to use for joining, default is space
-    def self.compact_and_join(values, delimiter: " ")
-      compacted_values = values.compact_blank.map(&:strip)
-      return compacted_values.first if compacted_values.one?
-
-      compacted_values.reduce(+"") do |result, value|
-        result << if value.end_with?(delimiter.strip)
-          value + " "
-        else
-          value + delimiter
-        end
-      end.delete_suffix(delimiter)
-    end
-
     attr_reader :cocina, :dates
 
     # Initialize the imprint with Cocina event data.
@@ -49,9 +33,9 @@ module CocinaDisplay
     # The entire imprint statement formatted as a string for display.
     # @return [String]
     def display_str
-      place_pub = self.class.compact_and_join([place_str, publisher_str], delimiter: " : ")
-      edition_place_pub = self.class.compact_and_join([edition_str, place_pub], delimiter: " - ")
-      self.class.compact_and_join([edition_place_pub, date_str], delimiter: ", ")
+      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?
@@ -65,25 +49,25 @@ module CocinaDisplay
     # The date portion of the imprint statement, comprising all unique dates.
     # @return [String]
     def date_str
-      self.class.compact_and_join(unique_dates_for_display.map(&:qualified_value))
+      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
-      self.class.compact_and_join(Janeway.enum_for("$.note[?@.type == 'edition'].value", cocina))
+      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
-      self.class.compact_and_join(locations_for_display, delimiter: " : ")
+      Utils.compact_and_join(locations_for_display, delimiter: " : ")
     end
 
     # The publisher information, combining all name values for publishers.
     # @return [String]
     def publisher_str
-      self.class.compact_and_join(Janeway.enum_for("$.contributor[?@.role[?@.value == 'publisher']].name[*].value", cocina), delimiter: " : ")
+      Utils.compact_and_join(Janeway.enum_for("$.contributor[?@.role[?@.value == 'publisher']].name[*].value", cocina), delimiter: " : ")
     end
 
     # Get the place name for a location, decoding from MARC if necessary.

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

@@ -46,6 +46,16 @@ module CocinaDisplay
       [new(strategy: :all, add_punctuation: false).build(titles)].flatten - full_title(titles)
     end
 
+    # Like the full title, but with any non-sorting characters and punctuation removed.
+    # @param titles [Array<Hash>] The titles to consider.
+    # @param catalog_links [Array<Hash>] The folio catalog links to check for digital serials part labels.
+    # @return [Array<String>] The sort title value(s) for Solr - array due to possible parallelValue
+    def self.sort_title(titles, catalog_links: [])
+      part_label = catalog_links.find { |link| link["catalog"] == "folio" }&.fetch("partLabel", nil)
+      [new(strategy: :first, add_punctuation: false, only_one_parallel_value: false, part_label: part_label, sortable: true).build(titles)]
+        .flatten.compact.map { |title| title.gsub(/[[:punct:]]*/, "").strip }
+    end
+
     # @param strategy [Symbol] ":first" selects a single title value based on precedence of
     # primary, untyped, first occurrence. ":all" returns an array containing all the values.
     # @param add_punctuation [boolean] whether the title should be formatted with punctuation (think of a structured
@@ -54,11 +64,13 @@ module CocinaDisplay
     # of primary, untyped, first occurrence.  When false, return an array containing all the parallel values.
     # Why? Think of e.g. title displayed in blacklight search results vs boosting values for ranking of search results
     # @param part_label [String] the partLabel to add for digital serials display
-    def initialize(strategy:, add_punctuation:, only_one_parallel_value: true, part_label: nil)
+    # @param sortable [boolean] whether the title is intended for sorting, and should have non-sorting parts removed
+    def initialize(strategy:, add_punctuation:, only_one_parallel_value: true, part_label: nil, sortable: false)
       @strategy = strategy
       @add_punctuation = add_punctuation
       @only_one_parallel_value = only_one_parallel_value
       @part_label = part_label
+      @sortable = sortable
     end
 
     # @param [Array<Hash>] cocina_titles the titles to consider
@@ -161,6 +173,10 @@ module CocinaDisplay
       @only_one_parallel_value
     end
 
+    def sortable?
+      @sortable
+    end
+
     # @return [Hash, nil] title that has status=primary
     def primary_title(cocina_titles)
       primary_title = cocina_titles.find { |title| title["status"] == "primary" }
@@ -221,7 +237,7 @@ module CocinaDisplay
     # rubocop:disable Metrics/CyclomaticComplexity
     # rubocop:disable Metrics/MethodLength
     # rubocop:disable Metrics/PerceivedComplexity
-    def rebuild_structured_value(cocina_title)
+    def rebuild_structured_value(cocina_title, sortable: false)
       result = ""
       part_name_number = ""
       cocina_title["structuredValue"].each do |structured_value| # rubocop:disable Metrics/BlockLength
@@ -235,8 +251,10 @@ module CocinaDisplay
         # additional types ignored here, e.g. name, uniform ...
         case structured_value["type"]&.downcase
         when "nonsorting characters"
-          padding = non_sorting_padding(cocina_title, value)
-          result = add_non_sorting_value(result, value, padding)
+          unless sortable?
+            padding = non_sorting_padding(cocina_title, value)
+            result = add_non_sorting_value(result, value, padding)
+          end
         when "part name", "part number"
           # even if there is a partLabel, use any existing structuredValue
           # part name/number that remains for non-digital serials purposes
@@ -286,7 +304,7 @@ module CocinaDisplay
     # rubocop:disable Metrics/PerceivedComplexity
     # rubocop:disable Metrics/AbcSize
     # rubocop:disable Metrics/CyclomaticComplexity
-    def main_title_from_structured_values(cocina_title)
+    def main_title_from_structured_values(cocina_title, sortable: false)
       result = ""
       # combine pieces of the cocina structuredValue into a single title
       cocina_title["structuredValue"].each do |structured_value|
@@ -299,8 +317,10 @@ module CocinaDisplay
 
         case structured_value["type"]&.downcase
         when "nonsorting characters"
-          padding = non_sorting_padding(cocina_title, value)
-          result = add_non_sorting_value(result, value, padding)
+          unless sortable?
+            padding = non_sorting_padding(cocina_title, value)
+            result = add_non_sorting_value(result, value, padding)
+          end
         when "main title", "title"
           result = if ["'", "-"].include?(result.last)
             [result, value].join

data/lib/cocina_display/utils.rb

@@ -0,0 +1,49 @@
+module CocinaDisplay
+  # Helper methods for string formatting, etc.
+  module Utils
+    # Join non-empty values into a string using provided delimiter.
+    # If values already end in delimiter (ignoring whitespace), join with a space instead.
+    # @param values [Array<String>] The values to compact and join
+    # @param delimiter [String] The delimiter to use for joining, default is space
+    # @return [String] The compacted and joined string
+    def self.compact_and_join(values, delimiter: " ")
+      compacted_values = values.compact_blank.map(&:strip)
+      return compacted_values.first if compacted_values.one?
+
+      compacted_values.reduce(+"") do |result, value|
+        result << if value.end_with?(delimiter.strip)
+          value + " "
+        else
+          value + delimiter
+        end
+      end.delete_suffix(delimiter)
+    end
+
+    # 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
+    # @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_nested_values(node, output) } if cocina.is_a?(Array)
+
+      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.3.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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nick Budak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-08 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,12 +170,20 @@ 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
 - sig/cocina_display.rbs
 homepage: https://sul-dlss.github.io/cocina_display/