perron 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf1b0d5483938df7b88423f3ecd72bffaf938eadcc49a3001a34fcb0156dfb9
-  data.tar.gz: cd8871c7ef91a102a45bcebbcdc8bbf385db3a83ffb34948cd0d3e49c14d8237
+  metadata.gz: 4b7d197a1f26d5fae6c488fe7be6aef6c3818e408d97b5d789f46111db3207be
+  data.tar.gz: 0cb809db9260c8e5ded0626f9d790dfb003b937892c1bbce022bcbdac3e5053d
 SHA512:
-  metadata.gz: 4d21cfbf61b54fb704990a23cbbf73285364e37ab722246c0202ecea37616398edcfe3fc9f841bc3cae9100108cb61e37200780c0e0ef667515f6e27319498e4
-  data.tar.gz: bed9e2b68bf2a5697a72a6b3bcb2dfcdb6898b93e31b6bc68b169583462d9e4a4f3e345dec8470077b2566dd31860e8ca97ce83cd82b8a01aff889ad0d5a7d14
+  metadata.gz: cc876ae9e8fb6daf1c6496c381efc05eba46fe5bbff9174502480488c34a4dbf5c94d9a360752942a53c395d7df6cb3b9e8342936e8e795b3ab3ccc20f6b3cdd
+  data.tar.gz: 99681d91d5d5ea2ffb8488ba4c93c27b2115aebde8132d6f0c8376a6b3e7819c62aef196b424e244af04d8ada7a12080c181cd0f44cf9d52c79125263c3f849b

data/Gemfile

@@ -4,7 +4,7 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "rails", "~> 7.2.0"
+gem "appraisal"
 
 group :development do
   gem "standard", "~> 1.50.0"

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    perron (0.17.0)
+    perron (0.18.0)
       csv
       json
+      mata (~> 0.8.0)
       psych
       rails (>= 7.2.0)
 
@@ -81,6 +82,10 @@ GEM
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
+    appraisal (2.5.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.4.1)
@@ -97,6 +102,14 @@ GEM
     drb (2.2.3)
     erb (5.0.1)
     erubi (1.13.1)
+    ffi (1.17.3-aarch64-linux-gnu)
+    ffi (1.17.3-aarch64-linux-musl)
+    ffi (1.17.3-arm-linux-gnu)
+    ffi (1.17.3-arm-linux-musl)
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-linux-musl)
     globalid (1.2.1)
       activesupport (>= 6.1)
     i18n (1.14.7)
@@ -109,6 +122,10 @@ GEM
     json (2.12.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
     loofah (2.24.1)
       crass (~> 1.0.2)
@@ -119,6 +136,9 @@ GEM
       net-pop
       net-smtp
     marcel (1.0.4)
+    mata (0.8.0)
+      listen (~> 3.0)
+      rack (>= 3.0)
     mini_mime (1.1.5)
     mini_portile2 (2.8.9)
     minitest (5.27.0)
@@ -202,6 +222,9 @@ GEM
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
     rake (13.3.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
     rdoc (6.14.2)
       erb
       psych (>= 4.0.0)
@@ -267,10 +290,10 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  appraisal
   debug (~> 1.11.0)
   minitest (~> 5.25, >= 5.25.5)
   perron!
-  rails (~> 7.2.0)
   rake (~> 13.3.0)
   rouge (~> 4.6.0)
   standard (~> 1.50.0)

data/app/controllers/perron/searches_controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Perron
+  class SearchesController < ApplicationController
+    before_action :force_json, only: %w[show]
+
+    def show
+      resources = search_scope.flat_map(&:all)
+      index = resources.map do |resource|
+        base_fields(resource).merge(additional_search_fields(resource))
+      end
+
+      render json: index
+    end
+
+    private
+
+    def force_json
+      request.format = :json
+    end
+
+    def search_scope
+      Perron
+        .configuration
+        .search_scope
+        .map { "Content::#{it.classify}".safe_constantize }
+        .compact_blank
+    end
+
+    def base_fields(resource)
+      {
+        slug: polymorphic_path(resource),
+        href: polymorphic_path(resource),
+        title: resource.try(:title) || resource.metadata.title,
+        headings: resource.extracted_headings.flatten.join(" "),
+        body: resource.sweeped_content
+      }
+    end
+
+    def additional_search_fields(resource)
+      return {} unless resource.class.search_fields_list.any?
+
+      resource.class.search_fields_list.to_h do |field|
+        [field, resource.public_send(field)]
+      end
+    end
+  end
+end

data/app/helpers/perron/feeds_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Perron
+  module FeedsHelper
+    def feeds(options = {}) = Perron::Feeds.new.render(options)
+  end
+end

data/app/helpers/perron/markdown_helper.rb

@@ -4,10 +4,10 @@ require "perron/markdown"
 
 module Perron
   module MarkdownHelper
-    def markdownify(content = nil, options = {}, &block)
-      processors = options.fetch(:process, [])
+    def markdownify(content = nil, process: [], &block)
+      text = block_given? ? capture(&block).strip_heredoc : content
 
-      Perron::Markdown.render(content || capture(&block).strip_heredoc, processors: processors)
+      Perron::Markdown.render(text, processors: process)
     end
   end
 end

data/app/helpers/perron/meta_tags_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Perron
+  module MetaTagsHelper
+    def meta_tags(options = {}) = Perron::Metatags.new(resource.metadata).render(options)
+
+    private
+
+    Resource = Data.define(:path, :collection, :metadata, :published_at)
+
+    def resource
+      return Resource.new(request.path, nil, @metadata, nil) if @metadata.present?
+
+      @resource || Resource.new(request.path, nil, {}, nil)
+    end
+  end
+end

data/bin/release

@@ -3,17 +3,32 @@
 VERSION=$1
 
 if [ -z "$VERSION" ]; then
-  echo "Error: The version number is required."
-  echo "Usage: $0 <version-number>"
+  echo "Error: Version number or bump type is required"
+  echo "  Usage: $0 <major|minor|patch|version-number>"
+
   exit 1
 fi
 
+if [[ "$VERSION" =~ ^(major|minor|patch)$ ]]; then
+  CURRENT=$(grep -o '"[^"]*"' ./lib/perron/version.rb | tr -d '"')
+  IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+
+  case $VERSION in
+    major) VERSION="$((MAJOR + 1)).0.0" ;;
+    minor) VERSION="$MAJOR.$((MINOR + 1)).0" ;;
+    patch) VERSION="$MAJOR.$MINOR.$((PATCH + 1))" ;;
+  esac
+fi
+
 printf "module Perron\n  VERSION = \"$VERSION\"\nend\n" > ./lib/perron/version.rb
+
 bundle
+
 git add Gemfile.lock lib/perron/version.rb
 git commit -m "Bump version for $VERSION"
 git push
 git tag v$VERSION
 git push --tags
-gem build perron.gemspec
-gem push "perron-$VERSION.gem"
+
+bundle exec rake build
+gem push "pkg/perron-$VERSION.gem"

data/lib/generators/perron/templates/README.md.tt

@@ -1,22 +1,24 @@
 # Data
 
-Perron can consume structured data from YML, JSON, or CSV files, making them available within your templates. This is useful for populating features, team members, or any other repeated data structure.
+Perron can consume structured data from YML, JSON or CSV files, making them available within views. This is useful for populating features, team members or any other repeated data structure.
 
 
 ## Usage
 
-To use a data file, instantiate `Perron::Site.data` with the basename of the file and iterate over the result.
+Access data sources using the `Content::Data` namespace with the class name matching the file's basename:
 ```erb
-<%% Perron::Site.data.features.each do |feature| %>
+<%% Content::Data::Features.all.each do |feature| %>
   <h4><%%= feature.name %></h4>
   <p><%%= feature.description %></p>
 <%% end %>
 ```
 
+Look up a single entry with `Content::Data::Features.find("advanced-search")`, where `"advanced-search"` matches the value of the entry's `id` field.
+
 
 ## File location and formats
 
-By default, Perron looks up `app/content/data/` for files with a `.yml`, `.json`, or `.csv` extension. For a `features` call, it would find `features.yml`, `features.json`, or `features.csv`. You can also provide a path to any data file, via `Perron::Data.new("path/to/data.json")`.
+By default, Perron looks up `app/content/data/` for files with a `.yml`, `.json` or `.csv` extension. For a `features` call, it would find `features.yml`, `features.json` or `features.csv`. Provide a path to any data resource in `/app/content/data/`, via `Content::Data.new("path/to/data-resource")`.
 
 
 ## Accessing data
@@ -30,12 +32,12 @@ feature[:name]
 
 ## Rendering
 
-You can render data collections directly using Rails-like partial rendering. When you call `render` on a data collection, Perron will automatically render a partial for each item.
+Render data collections directly using Rails-like partial rendering:
 ```erb
-<%%= render Perron::Site.data.features %>
+<%%= render Content::Data::Features.all %>
 ```
 
-This expects a partial at `app/views/content/features/_feature.html.erb` that will be rendered once for each feature in your data file. The individual record is made available as a local variable matching the singular form of the collection name.
+This expects a partial at `app/views/content/features/_feature.html.erb` that will be rendered once for each item in `Content::Data::Features.all`. The individual record is made available as a local variable matching the singular form of the collection name.
 ```erb
 <!-- app/views/content/features/_feature.html.erb -->
 <div class="feature">
@@ -43,3 +45,25 @@ This expects a partial at `app/views/content/features/_feature.html.erb` that wi
   <p><%%= feature.description %></p>
 </div>
 ```
+
+
+## Data structure
+
+Data resources must contain an array of objects. Each record should include an `id` field if used with [associations](/docs/resources/#associations) or with the `find` method:
+```yaml
+# app/content/data/authors.yml
+- id: rails-designer
+  name: Rails Designer
+  bio: Creator of Perron
+
+- id: cam
+  name: Cam
+  bio: Contributing author
+```
+
+
+## Enumerable methods
+
+[!label v0.17.0+]
+
+All data objects support enumerable methods like `select`, `sort_by`, `first` and `count`. See [Enumerable methods](/docs/rendering/#enumerable-methods) for the full list of available methods.

data/lib/generators/perron/templates/initializer.rb.tt

@@ -1,16 +1,20 @@
 Perron.configure do |config|
-  # View all options: https://perron.railsdesigner.com/docs/configuration/
+  # For all options check out:
+  # https://perron.railsdesigner.com/docs/configuration/
 
-  # config.site_name = "Chirp Form"
-
-  # The build mode for Perron. Can be :standalone (SSG) or :integrated (alongside your Rails app)
+  # The build mode for Perron. Can be :standalone (SSG, default) or :integrated (alongside your Rails app)
   # config.mode = :standalone
 
+  # Enable Live Reload with DOM Morphing in development
+  # config.live_reload = true
+
   # config.default_url_options = {host: "chirpform.com", protocol: "https", trailing_slash: true}
 
   # The options hash is passed directly to the chosen library
   # config.markdown_options = {}
 
+  # config.site_name = "Chirp Form"
+
   # Set meta title suffix
   # config.metadata.title_suffix = nil
   # config.metadata.title_separator = " — "

data/lib/generators/rails/content/USAGE

@@ -2,63 +2,65 @@ Description:
     Generates content model scaffold (controller, views, routes) or creates
     new content files from templates.
 
+Arguments:
+    NAME                Name of the content model (singular or plural)
+    actions             Actions to generate (default: index show)
+
+Options:
+    --new [TITLE]                   Create new content file instead of scaffold
+    --data [SOURCE...]              Create data source files (default extension: .yml)
+    --force-plural                  Use plural form for model name and class
+    --[no-]include-root             Include root action and route
+                                    (default: true for pages, false otherwise)
+
 Examples:
-    Generate content scaffold:
+    Generate basic content scaffold:
         rails generate content Post
         rails generate content Post index
         rails generate content Post index show
 
-    This will create:
+    Creates:
         app/content/posts/
         app/models/content/post.rb
         app/controllers/content/posts_controller.rb
         app/views/content/posts/index.html.erb
         app/views/content/posts/show.html.erb
 
-    And adds: resources :posts, module: :content, only: %w[index show]
+    Adds route:
+        resources :posts, module: :content, only: %w[index show]
 
     Generate pages scaffold with root:
         rails generate content Page
 
-    This will additionally create:
+    Additionally creates:
         app/content/pages/root.erb
-        def root action in Content::PagesController
-        root route in config/routes.rb (if not already defined)
+        root action in app/controllers/content/pages_controller.rb
+        root route in config/routes.rb
 
-    Skip root generation for pages:
+    Control root generation:
         rails generate content Page --no-include-root
-
-    Include root for non-pages content:
         rails generate content Article --include-root
 
-    Generate content scaffold with data sources:
+    Generate scaffold with data sources:
         rails generate content Product --data countries products
         rails generate content Product --data countries.json products.yml
 
-    This will additionally create data source files in app/content/products/
-    and add sources/template_source class methods to the model.
+    Creates data source files in app/content/data/ and adds
+    .sources and .template_source class methods to the model.
+
+    Adds .sources and .template_source class methods to model.
 
     Create new content file from template:
         rails generate content Post --new
         rails generate content Post --new "My First Post"
 
-    This will create a new content file in app/content/posts/ using:
-        - YYYY-MM-DD-template.*.tt (if exists, with date prefix)
-        - template.*.tt (if exists, without date prefix)
-        - Empty file with frontmatter dashes (if no template)
+    Creates a new content file in app/content/posts/ using:
+        1. YYYY-MM-DD-template.*.tt (if exists, with date prefix)
+        2. template.*.tt (if exists, without date prefix)
+        3. Empty file with frontmatter dashes (if no template)
 
     Template files support ERB:
         ---
         title: <%= @title %>
         published_at: <%= Time.current %>
         ---
-
-Arguments:
-    NAME: Name of the content model (singular or plural)
-    actions: Actions to generate (default: index show)
-
-Options:
-    --new [TITLE]: Create new content file instead of scaffold
-    --data [source1(.ext) source2(.ext)]: Create data source files (default extension: .yml)
-    --force-plural: Use plural form for model name and class
-    --[no-]include-root: Include root action and route (default: true for pages, false otherwise)

data/lib/generators/rails/content/content_generator.rb

@@ -76,7 +76,7 @@ module Rails
         options[:data].each do |source|
           name, extension = source.split(".", 2)
 
-          create_file File.join(content_directory, "#{name}.#{extension || "yml"}"), ""
+          create_file File.join("app", "content", "data", "#{name}.#{extension || "yml"}"), ""
         end
       end
 
@@ -85,13 +85,12 @@ module Rails
         return unless should_include_root?
 
         inject_into_class "app/controllers/content/#{plural_file_name}_controller.rb", "Content::#{plural_class_name}Controller" do
-          <<-RUBY
+          <<~RUBY
+            def root
+              @resource = Content::#{class_name}.root
 
-        def root
-          @resource = Content::#{class_name}.root
-
-          render :show
-        end
+              render :show
+            end
           RUBY
         end
       end

data/lib/generators/rails/content/templates/controller.rb.tt

@@ -1,8 +1,4 @@
 class Content::<%= plural_class_name %>Controller < ApplicationController
-<%- if pages_controller? -%>
-  include Perron::Root
-<%- end -%>
-
 <%- if actions.include?("index") -%>
   def index
     @resources = Content::<%= class_name %>.all
@@ -11,7 +7,7 @@ class Content::<%= plural_class_name %>Controller < ApplicationController
 <%- end -%>
 <%- if actions.include?("show") -%>
   def show
-    @resource = Content::<%= class_name %>.find(params[:id])
+    @resource = Content::<%= class_name %>.find!(params[:id])
   end
 <%- end -%>
 end

data/lib/generators/rails/content/templates/model.rb.tt

@@ -1,13 +1,13 @@
 class Content::<%= class_name %> < Perron::Resource
 <% if data_sources? -%>
-
   sources <%= data_sources.map { ":#{it}" }.join(", ") %>
 
   def self.source_template(sources)
-    <<~TEMPLATE
+    <<~MARKDOWN
     ---
     ---
-    TEMPLATE
+
+    MARKDOWN
   end
 <% end -%>
 end

data/lib/perron/collection.rb

@@ -16,11 +16,20 @@ module Perron
     end
 
     def all(resource_class = "Content::#{name.classify}".safe_constantize)
-      load_resources(resource_class).select(&:published?)
+      Perron::Relation.new(load_resources(resource_class).select(&:published?))
     end
     alias_method :resources, :all
 
     def find(slug, resource_class = Resource)
+      Perron.deprecator.deprecation_warning(
+        :find,
+        "Collection#find will return nil instead of raising in the next major version. Use #find! to raise an error."
+      )
+
+      find!(slug, resource_class)
+    end
+
+    def find!(slug, resource_class = Resource)
       resource = load_resources(resource_class).find { it.slug == slug }
 
       return resource if resource

data/lib/perron/configuration.rb

@@ -13,17 +13,17 @@ module Perron
     def initialize
       @config = ActiveSupport::OrderedOptions.new
 
-      @config.site_name = nil
-      @config.site_description = nil
-
       @config.output = "output"
 
       @config.mode = :standalone
 
-      @config.allowed_extensions = %w[erb md]
+      @config.live_reload = false
+      @config.live_reload_watch_paths = %w[app/content app/views app/assets]
+      @config.live_reload_skip_paths = %w[app/assets/builds]
 
       @config.exclude_from_public = %w[assets storage]
       @config.excluded_assets = %w[action_cable actioncable actiontext activestorage rails-ujs trix turbo]
+      @config.allowed_extensions = %w[erb md]
 
       @config.view_unpublished = Rails.env.development?
 
@@ -35,11 +35,16 @@ module Perron
 
       @config.markdown_options = {}
 
+      @config.search_scope = []
+
       @config.sitemap = ActiveSupport::OrderedOptions.new
       @config.sitemap.enabled = false
       @config.sitemap.priority = 0.5
       @config.sitemap.change_frequency = :monthly
 
+      @config.site_name = nil
+      @config.site_description = nil
+
       @config.metadata = ActiveSupport::OrderedOptions.new
       @config.metadata.title_separator = " — "
     end

data/lib/perron/content/data.rb

@@ -2,9 +2,13 @@
 
 module Content
   module Data
+    def self.new(identifier)
+      Perron::DataSource.new(identifier)
+    end
+
     def self.const_missing(name)
-      klass = Class.new(Perron::Data) do
-        def self.const_missing(nested_name) = const_set(nested_name, Class.new(Perron::Data))
+      klass = Class.new(Perron::DataSource) do
+        def self.const_missing(nested_name) = const_set(nested_name, Class.new(Perron::DataSource))
       end
 
       const_set(name, klass)

data/lib/perron/data_source/class_methods.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Perron
+  class DataSource < SimpleDelegator
+    module ClassMethods
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def all
+          parts = name.to_s.split("::").drop(2)
+          identifier = parts.empty? ? name.demodulize.underscore : parts.map(&:underscore).join("/")
+
+          new(identifier)
+        end
+
+        def find(id)
+          all.find { it[:id] == id || it["id"] == id }
+        end
+
+        def count = all.size
+
+        def first = all.first
+
+        def second = all[1]
+
+        def third = all[2]
+
+        def fourth = all[3]
+
+        def fifth = all[4]
+
+        def forty_two = all[41]
+
+        def last = all.last
+
+        def take(n) = all.first(n)
+
+        def path_for(identifier)
+          path = Pathname.new(identifier)
+
+          return path.to_s if path.file? && path.absolute?
+
+          base_path = Rails.root.join("app", "content", "data")
+
+          SUPPORTED_EXTENSIONS.lazy.map { base_path.join("#{identifier}#{it}") }.find(&:exist?)&.to_s
+        end
+
+        def path_for!(identifier)
+          path_for(identifier).tap do |path|
+            raise Errors::FileNotFoundError, "No data file found for `#{identifier}`" unless path
+          end
+        end
+
+        def directory?(identifier) = Dir.exist?(Rails.root.join("app", "content", "data", identifier))
+      end
+    end
+  end
+end

data/lib/perron/data_source/helper_context.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Perron
+  class DataSource < SimpleDelegator
+    class HelperContext
+      include Singleton
+
+      def initialize
+        self.class.include ActionView::Helpers::AssetUrlHelper
+        self.class.include ActionView::Helpers::DateHelper
+        self.class.include Rails.application.routes.url_helpers
+      end
+
+      def get_binding = binding
+
+      def default_url_options = Perron.configuration.default_url_options || {}
+    end
+    private_constant :HelperContext
+  end
+end