phlex-hanami 0.1.0 → 0.2.0.pre.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 066d1770e9e59fc2e7a2a1e5a333be685bdee0c94180efd155a578af2f47d224
-  data.tar.gz: dab7797c0500df8bdaeaf8c856628e9b6a876e88e95511fc5bdbe18f4a09c1a7
+  metadata.gz: d51a4710b34ce6bb8d1a140f7df3fdae00006df8fd23b39c84506297e12f64df
+  data.tar.gz: 18954a7148a4d46c0b3053dadc7ccd534a25c9276eabe317f01274d9a4ce377a
 SHA512:
-  metadata.gz: 3acf4d4ec8b5ada0374b05f249cfe838351b93b5ac06a41f5876543b9b8b0725b442e89f7fe7414a827bcc7290fa7a4849dab25ed75b0802e2c762d7913788c9
-  data.tar.gz: 72f5b9ba2a7bc3aa46c16d4d548eebacd5825efe6d7476cc29bb1167cb0b5547a5ffd18fcf5edb1eca732dff1ce777478696597ae86529d5190b7da64fb1dfa6
+  metadata.gz: c3a536625ff7017b56129fd4f151d194240e9dfa4427d3f4d774cb1bb68ef3fd61dd069f7f7b7eef347e90f2339b9596da0ce737df90f1451c6ae81096186b3a
+  data.tar.gz: 178cedf68bfaed0844171fbfd6a935b9c931901f296c59ba922e957ba7caabf825bbd052bf3ce384255df4df7f90a4aa7108ed5d60e08d3102c8d646e4d64b87

data/CHANGELOG.md

@@ -1,5 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
-## [0.1.0] - 2024-12-07
+## [v0.2.0-alpha.1] - 2024-10-05
+
+Initial alpha release by the new maintainer [@aaronmallen](https://github.com/aaronmallen).
+
+## [v0.1.0] - 2024-12-07
+
+Initial release, by the previous maintainer [@stephannv](https://github.com/stephannv).
 
-- Initial release
+[Unreleased]: https://github.com/aaronmallen/phlex-hanami/compare/0.1.0...HEAD
+[v0.1.0]: https://github.com/stephannv/phlex-hanami/releases/tag/v0.1.0

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2024 stephann
+Copyright (c) 2026 Aaron Allen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/phlex/hanami/context.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # The view context used when the hanami-view gem is not bundled.
+    #
+    # Hanami builds a context once per request and hands it to the view as `context:`. When
+    # hanami-view is bundled that context is a `Hanami::View::Context` and this class is unused;
+    # otherwise phlex-hanami defines a `Views::Context` subclass of this in every slice.
+    #
+    # The public surface mirrors `Hanami::View::Context` so that a view reads the same either way.
+    #
+    # @api public
+    # @since 0.2.0
+    class Context
+      extend ::Hanami::SliceConfigurable
+
+      # @api private
+      # @since 0.2.0
+      def self.configure_for_slice(slice)
+        extend SliceConfiguredContext.new(slice)
+      end
+
+      # The app's inflector.
+      #
+      # @return [Dry::Inflector]
+      #
+      # @api public
+      # @since 0.2.0
+      attr_reader :inflector
+
+      # @see SliceConfiguredContext#define_new
+      #
+      # @api private
+      # @since 0.2.0
+      def initialize(inflector: nil, routes: nil, assets: nil, request: nil, i18n: nil, **)
+        @inflector = inflector
+        @routes = routes
+        @assets = assets
+        @request = request
+        @i18n = i18n
+        @content_for = {}
+      end
+
+      # The slice's assets.
+      #
+      # @return [Hanami::Assets]
+      #
+      # @raise [Hanami::ComponentLoadError] when hanami-assets is not bundled, or no assets exist
+      #
+      # @api public
+      # @since 0.2.0
+      def assets
+        raise ::Hanami::ComponentLoadError, "Assets not available. #{assets_hint}" unless @assets
+
+        @assets
+      end
+
+      # Store a string of markup for later use, or read back what was stored.
+      #
+      # @param key [Symbol] the content key
+      # @param value [String, nil] the content, when no block is given
+      #
+      # @return [String, nil]
+      #
+      # @api public
+      # @since 0.2.0
+      def content_for(key, value = nil)
+        if block_given?
+          @content_for[key] = yield
+          nil
+        elsif value
+          @content_for[key] = value
+          nil
+        else
+          @content_for[key]
+        end
+      end
+
+      # The current request's CSRF token.
+      #
+      # @return [String]
+      #
+      # @raise [Hanami::ComponentLoadError] when there is no request
+      #
+      # @api public
+      # @since 0.2.0
+      def csrf_token
+        request.session[::Hanami::Action::CSRFProtection::CSRF_TOKEN]
+      end
+
+      # The flash hash for the current request.
+      #
+      # @raise [Hanami::ComponentLoadError] when there is no request
+      #
+      # @api public
+      # @since 0.2.0
+      def flash
+        request.flash
+      end
+
+      # The slice's i18n backend.
+      #
+      # @raise [Hanami::ComponentLoadError] when the i18n gem is not bundled
+      #
+      # @api public
+      # @since 0.2.0
+      def i18n
+        raise ::Hanami::ComponentLoadError, "the i18n gem is required to access translations" unless @i18n
+
+        @i18n
+      end
+
+      # @api private
+      # @since 0.2.0
+      def initialize_copy(source)
+        super
+        @content_for = source.instance_variable_get(:@content_for).dup
+      end
+
+      # The current request, when the view is rendered from an action.
+      #
+      # @return [Hanami::Action::Request]
+      #
+      # @raise [Hanami::ComponentLoadError] when the view is not rendered from a request
+      #
+      # @api public
+      # @since 0.2.0
+      def request
+        unless @request
+          raise ::Hanami::ComponentLoadError, <<~MESSAGE
+            Request not available. Only views rendered from Hanami::Action instances have a request.
+          MESSAGE
+        end
+
+        @request
+      end
+
+      # Whether a request is available.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      # @since 0.2.0
+      def request?
+        !!@request
+      end
+
+      # The app's routes helper.
+      #
+      # @return [Hanami::Slice::RoutesHelper]
+      #
+      # @raise [Hanami::ComponentLoadError] when hanami-router is not bundled or routes are undefined
+      #
+      # @api public
+      # @since 0.2.0
+      def routes
+        raise ::Hanami::ComponentLoadError, "the hanami-router gem is required to access routes" unless @routes
+
+        @routes
+      end
+
+      # The session for the current request.
+      #
+      # @raise [Hanami::ComponentLoadError] when there is no request
+      #
+      # @api public
+      # @since 0.2.0
+      def session
+        request.session
+      end
+
+      private
+
+      def assets_hint
+        if ::Hanami.bundled?("hanami-assets")
+          "Have you put files into your assets directory?"
+        else
+          "The hanami-assets gem is required to access assets."
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami/errors/error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Base class for every error raised by phlex-hanami.
+    #
+    # @api public
+    # @since 0.2.0
+    class Error < StandardError
+    end
+  end
+end

data/lib/phlex/hanami/errors/missing_context_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Raised when a view reaches for the Hanami view context but was rendered without one.
+    #
+    # @api public
+    # @since 0.2.0
+    class MissingContextError < Error
+      # @api private
+      # @since 0.2.0
+      def initialize(view_class)
+        super(<<~MESSAGE)
+          #{view_class} was rendered without a Hanami view context.
+
+          Views rendered from an action are given one automatically. When rendering a view yourself,
+          pass one:
+
+            #{view_class}.call(context: MyApp::Views::Context.new)
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/phlex/hanami/extensions/slice.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    module Extensions
+      # Installs phlex-hanami into every slice, including the app.
+      #
+      # Prepended onto `Hanami::Slice::ClassMethods` so that it runs for the app and each of its
+      # slices as they are prepared. Two things happen:
+      #
+      # 1. Phlex classes are registered in the slice container as classes rather than instances.
+      #    `Dry::System` would otherwise call `new` on them while resolving, which raises for any
+      #    view with a real initializer, and a memoized Phlex instance can only render once.
+      # 2. A `Views::Context` is defined for the slice when hanami-view is not bundled, filling the
+      #    third-party slot `Hanami::Extensions::Action::SliceConfiguredAction#view_context_class`
+      #    looks in.
+      #
+      # @api private
+      # @since 0.2.0
+      module Slice
+        # Returns Phlex classes as classes, and everything else as the loader would.
+        #
+        # `component.loader.constant` is what the default autoloading loader already calls, so no
+        # extra loading happens here and a constant that fails to load still raises
+        # `Dry::System::ComponentNotLoadableError`.
+        #
+        # @api private
+        # @since 0.2.0
+        COMPONENT_INSTANCE = proc { |component, *args, **kwargs|
+          constant = component.loader.constant(component)
+
+          if constant.is_a?(Class) && constant < Phlex::SGML
+            constant
+          else
+            component.loader.call(component, *args, **kwargs)
+          end
+        }
+
+        # @api private
+        # @since 0.2.0
+        def prepare(provider_name = nil)
+          result = super
+
+          unless provider_name
+            Slice.register_phlex_components(self)
+            Slice.define_view_context(self)
+          end
+
+          result
+        end
+
+        class << self
+          # Defines `Views::Context` for the slice when nothing else has.
+          #
+          # Does nothing when hanami-view is bundled, because Hanami defines its own richer context
+          # there, and nothing when the user has defined one themselves.
+          #
+          # @api private
+          # @since 0.2.0
+          def define_view_context(slice)
+            return if ::Hanami.bundled?("hanami-view")
+
+            namespace = views_namespace(slice)
+            return if namespace.const_defined?(:Context, false)
+
+            # The class is anonymous at this point, so the slice cannot be inferred from its name
+            # the way `Hanami::SliceConfigurable` would; configure it explicitly instead.
+            namespace.const_set(:Context, ::Class.new(Context).tap { |klass| klass.configure_for_slice(slice) })
+          end
+
+          # Installs {COMPONENT_INSTANCE} as the default for the slice container's component dirs.
+          #
+          # `Dry::System::Config::ComponentDirs` re-applies its defaults every time the dirs are
+          # read, and only where a dir has not configured the setting itself, so setting this after
+          # the dirs have been added covers all of them and clobbers nothing.
+          #
+          # @api private
+          # @since 0.2.0
+          def register_phlex_components(slice)
+            component_dirs = slice.container.config.component_dirs
+            return if component_dirs.configured?(:instance)
+
+            component_dirs.instance = COMPONENT_INSTANCE
+          end
+
+          private
+
+          def views_namespace(slice)
+            if slice.namespace.const_defined?(:Views, false)
+              slice.namespace.const_get(:Views, false)
+            else
+              slice.namespace.const_set(:Views, ::Module.new)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami/helpers.rb

@@ -1,9 +1,68 @@
+# frozen_string_literal: true
+
+require "hanami/view"
+require "hanami/extensions/view/standard_helpers"
+
+# Hanami's helpers return `SafeString`s meant to be interpolated into a template. Marking the class
+# as a Phlex safe object lets Phlex emit them without escaping — both through `raw` and, more often,
+# as the return value of a block.
+Hanami::View::HTML::SafeString.include(Phlex::SGML::SafeObject)
+
 module Phlex
   module Hanami
+    # Hanami's standard helper library, for Phlex views that want it.
+    #
+    # Opt in per base class; it is not included in {View}, because it adds around twenty methods and
+    # needs the hanami-view gem, and neither should depend on what happens to be in your Gemfile.
+    #
+    # @example
+    #   module MyApp
+    #     class View < Phlex::Hanami::View
+    #       include Phlex::Hanami::Helpers
+    #     end
+    #   end
+    #
+    #   class Edit < MyApp::View
+    #     def view_template
+    #       raw form_for("post", path(:posts)) { |f| f.text_field(:title) + f.submit("Save") }
+    #     end
+    #   end
+    #
+    # Most of Hanami's helpers duplicate something Phlex already does better — Phlex escapes by
+    # default and is itself a tag builder — so reach for `form_for`, `format_number` and the asset
+    # helpers, and write everything else as ordinary Phlex.
+    #
+    # @api public
+    # @since 0.2.0
     module Helpers
-      def self.included(base)
-        base.include AssetsHelper
-        base.include ContextHelper
+      # Hanami's helper library defines two methods Phlex already owns.
+      #
+      # Both of Hanami's return strings to interpolate; Phlex's write into the output buffer.
+      # Letting Hanami's win breaks `raw` silently — the helper's output simply never appears — and
+      # `raw` is the method you need in order to emit a helper's result at all.
+      #
+      # @api private
+      # @since 0.2.0
+      OVERRIDDEN_METHODS = {
+        raw: Phlex::SGML.instance_method(:raw),
+        tag: Phlex::HTML.instance_method(:tag),
+      }.freeze
+
+      # Phlex's implementations, mixed back in over Hanami's.
+      #
+      # @api private
+      # @since 0.2.0
+      PhlexMethods = ::Module.new do
+        OVERRIDDEN_METHODS.each do |name, method|
+          define_method(name) { |*args, **options, &block| method.bind_call(self, *args, **options, &block) }
+        end
+      end
+
+      # @api private
+      # @since 0.2.0
+      def self.included(view_class)
+        view_class.include(::Hanami::Extensions::View::StandardHelpers)
+        view_class.include(PhlexMethods)
       end
     end
   end

data/lib/phlex/hanami/layout.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # The base class for layouts.
+    #
+    # A layout is an ordinary Phlex class that yields the view's body. Name one `Views::Layout` in a
+    # slice's namespace and every view in that slice renders inside it; set a different one with
+    # `layout`, or opt out with `layout nil`.
+    #
+    # The view's body is rendered before the layout, so anything the view puts on the context — a
+    # `content_for(:page_title, ...)`, say — is already there when the layout renders its `head`.
+    #
+    # @example
+    #   # app/views/layout.rb
+    #   module MyApp
+    #     module Views
+    #       class Layout < Phlex::Hanami::Layout
+    #         def view_template
+    #           doctype
+    #           html do
+    #             head { title { hanami_context.content_for(:page_title) || "MyApp" } }
+    #             body { yield }
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @api public
+    # @since 0.2.0
+    class Layout < Phlex::HTML
+      include Renderable
+
+      # A layout is never itself wrapped in a layout.
+      layout nil
+    end
+  end
+end