perron 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 709c1a304332c522dd7e425824f2718b1a84994db9695b842cddab07fa2a6c2d
-  data.tar.gz: cd636faddbff65dd1cc27652fb9141a936ce7df7e5f4fca1e156fd7b1ff27522
+  metadata.gz: 4b7d197a1f26d5fae6c488fe7be6aef6c3818e408d97b5d789f46111db3207be
+  data.tar.gz: 0cb809db9260c8e5ded0626f9d790dfb003b937892c1bbce022bcbdac3e5053d
 SHA512:
-  metadata.gz: 40df8027fb5974b0670a80b4c61e918da1f3dd7cec833e5fab48cdb606ddb9d9e56480cb69ad3c3033c2fdf1deb09e0c105cb15730cb92581e1d57c3db57ce3f
-  data.tar.gz: af0d331538e600ad27d23f9377d6cdabcc1f3142ad7d07de517b002334c0414896edb45d6d0d5d6ab50a6af81be12f4b2bf667c15e8bc50e211a824b6701d1b2
+  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.16.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,25 +1,25 @@
 Perron.configure do |config|
-  # config.output = "output"
+  # For all options check out:
+  # https://perron.railsdesigner.com/docs/configuration/
 
-  # config.site_name = "Chirp Form"
-
-  # The build mode for Perron. Can be :standalone or :integrated
+  # The build mode for Perron. Can be :standalone (SSG, default) or :integrated (alongside your Rails app)
   # config.mode = :standalone
 
-  # In `integrated` mode, the root is skipped by default. Set to `true` to enable
-  # config.include_root = false
+  # Enable Live Reload with DOM Morphing in development
+  # config.live_reload = true
 
-  # config.default_url_options = {host: "helptail.com", protocol: "https", trailing_slash: 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 = {}
 
-  # Set default meta values
-  # Examples:
-  # - `config.metadata.description = "Add forms to any static site. Display responses anywhere."`
-  # - `config.metadata.author = "Chirp Form Team"`
+  # config.site_name = "Chirp Form"
 
   # Set meta title suffix
   # config.metadata.title_suffix = nil
   # config.metadata.title_separator = " — "
+
+  # Set default meta values
+  # config.metadata.description = "Add forms to any static site. Display responses anywhere."
+  # config.metadata.author = "Chirp Form Team"
 end

data/lib/generators/rails/content/USAGE

@@ -2,40 +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
+
+    Additionally creates:
+        app/content/pages/root.erb
+        root action in app/controllers/content/pages_controller.rb
+        root route in config/routes.rb
+
+    Control root generation:
+        rails generate content Page --no-include-root
+        rails generate content Article --include-root
+
+    Generate scaffold with data sources:
+        rails generate content Product --data countries products
+        rails generate content Product --data countries.json products.yml
+
+    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
-    --force-plural: Use plural form for model name and class

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

@@ -8,8 +8,11 @@ module Rails
       source_root File.expand_path("templates", __dir__)
 
       class_option :force_plural, type: :boolean, default: false, desc: "Forces the use of a plural model name and class"
+      class_option :include_root, type: :boolean, default: nil, desc: "Include root action and route (defaults to true for pages)"
       class_option :new, type: :string, default: nil, banner: "TITLE",
         desc: "Create a new content file from template instead of generating scaffold"
+      class_option :data, type: :array, default: [], banner: "source1(.ext) source2(.ext)",
+        desc: "Specify data sources with optional extensions (defaults to .yml)"
 
       argument :actions, type: :array, default: %w[index show], banner: "actions", desc: "Specify which actions to generate (index/show)"
 
@@ -60,25 +63,51 @@ module Rails
         FileUtils.mkdir_p(content_directory)
       end
 
-      def create_pages_root
+      def add_content_route
         return if @content_mode
-        return unless pages_controller?
 
-        template "root.erb.tt", File.join(content_directory, "root.erb")
+        route "resources :#{plural_file_name}, module: :content, only: %w[#{actions.join(" ")}]"
       end
 
-      def add_content_route
+      def create_data_sources
         return if @content_mode
+        return if options[:data].empty?
 
-        route "resources :#{plural_file_name}, module: :content, only: %w[#{actions.join(" ")}]"
+        options[:data].each do |source|
+          name, extension = source.split(".", 2)
+
+          create_file File.join("app", "content", "data", "#{name}.#{extension || "yml"}"), ""
+        end
+      end
+
+      def add_root_action
+        return if @content_mode
+        return unless should_include_root?
+
+        inject_into_class "app/controllers/content/#{plural_file_name}_controller.rb", "Content::#{plural_class_name}Controller" do
+          <<~RUBY
+            def root
+              @resource = Content::#{class_name}.root
+
+              render :show
+            end
+          RUBY
+        end
+      end
+
+      def create_root_content_file
+        return if @content_mode
+        return unless should_include_root?
+
+        template "root.erb.tt", File.join(content_directory, "root.erb")
       end
 
       def add_root_route
         return if @content_mode
-        return unless pages_controller?
+        return unless should_include_root?
         return if root_route_exists?
 
-        inject_into_file "config/routes.rb", "  root to: \"content/pages#root\"\n", before: /^\s*end\s*$/
+        route "root to: \"content/#{plural_file_name}#root\""
       end
 
       private
@@ -99,14 +128,6 @@ module Rails
 
       def pages_controller? = plural_file_name == "pages"
 
-      def root_route_exists?
-        routes = File.join(destination_root, "config", "routes.rb")
-
-        return false unless File.exist?(routes)
-
-        File.read(routes).match?(/\broot\s+to:/)
-      end
-
       def template_file
         @template_file ||= Dir.glob(File.join(content_directory, "{YYYY-MM-DD-,}template.*.tt")).first
       end
@@ -121,6 +142,23 @@ module Rails
           end
         end
       end
+
+      def should_include_root?
+        options[:include_root].nil? ? pages_controller? : options[:include_root]
+      end
+
+      def root_route_exists?
+        routes = File.join(destination_root, "config", "routes.rb")
+        return false unless File.exist?(routes)
+
+        File.read(routes).match?(/\broot\s+to:/)
+      end
+
+      def data_sources
+        options[:data].map { it.split(".").first }
+      end
+
+      def data_sources? = !options[:data].empty?
     end
   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,2 +1,13 @@
 class Content::<%= class_name %> < Perron::Resource
+<% if data_sources? -%>
+  sources <%= data_sources.map { ":#{it}" }.join(", ") %>
+
+  def self.source_template(sources)
+    <<~MARKDOWN
+    ---
+    ---
+
+    MARKDOWN
+  end
+<% end -%>
 end

data/lib/generators/rails/content/templates/root.erb.tt

@@ -1,4 +1,4 @@
 ---
 ---
 
-Find me in `app/content/pages/root.erb`
+Find me in `app/content/<%= plural_file_name %>/root.erb`

data/lib/generators/rails/content/templates/show.html.erb.tt

@@ -3,5 +3,5 @@
     <%%= @resource.filename %>
   </h1>
 
-  <%%= markdownify @resource.content %>
+  <%%= @resource.content %>
 </article>

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,18 +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.include_root = false
 
-      @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?
 
@@ -36,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
@@ -53,7 +57,11 @@ module Perron
 
     def mode = @config.mode.to_s.inquiry
 
-    def exclude_root? = !@config.include_root
+    def additional_routes
+      @additional_routes || (mode.integrated? ? [] : %w[root_path])
+    end
+
+    attr_writer :additional_routes
 
     def url
       options = Perron.configuration.default_url_options

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)