phlex-hanami 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94b5188b274ac90980037b58873c197a1ce6fc343d184e9302b41082426fc57b
-  data.tar.gz: 8cdb0e7203df09112ec77a082e6c727520746e25cd3345071c873722c1588af0
+  metadata.gz: 301d34d14bd2989ab0ab899fd6f76e38b5a8e8b1a3fcffa182f6ece292652e81
+  data.tar.gz: 74e00aebe59f62800ad37bd576ab97f71efbfbabb536d5fa115e8b2ce5789509
 SHA512:
-  metadata.gz: 4ba875c6722dc031fd2911c5e479295b31cc5919b3f881b5f969c32cbcd3797e3b9e87145315aff2289d07fef2d8bcdf04b5dfdce020eeac1e10b914c2bd4211
-  data.tar.gz: 14f5c3441510387fee8927a7eed2722997fc4a6cb3bf81d3e803075d0083dbdf6747c1e670ac5eac069cb9c0fc2fea6e3f8c6960bcfcc10594e08f8fe46586a0
+  metadata.gz: 84d0aec75d54b2e1e7be95d57c9d2c7e9afb560abd4ec7b86065136618775988a33776da0195c71222f9921c628c7b3b6168ca8cc84710f8a18709114210d6a6
+  data.tar.gz: 8ab7a57fac797d8daa565d6335ed9efbe2b1cfde7c0f67f30ab98a5c8c01341ee6a2b46ebb0eced44807084080fc6f5d73bec15914f16780163143f4b1b13cc3

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v0.2.1] - 2026-09-26
+
+### Added
+
+- `Phlex::Hanami::Props`, an opt in `prop` for views and components typed with dry-types. The type coerces as
+  well as checks, so a view can turn a request param into an Integer. Literal still works as before.
+
 ## [v0.2.0] - 2026-09-10
 
 First stable release by the new maintainer. It shares no code with 0.1.0, so treat an upgrade from 0.1.0 as a move

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Raised when a prop's type rejects the value it was given.
+    #
+    # The type's own error, when there is one, is kept as the `cause`.
+    #
+    # @api public
+    # @since 0.3.0
+    class InvalidPropError < Error
+      # @api private
+      # @since 0.3.0
+      #: (Module, Symbol, String) -> void
+      def initialize(view_class, name, reason)
+        super(<<~MESSAGE)
+          #{view_class} was given an invalid #{name.inspect} prop.
+
+            #{reason}
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/phlex/hanami/props.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Declared props, typed with dry-types.
+    #
+    # Opt in per class. Each `prop` names a keyword `initialize` takes and the type its value goes
+    # through, and the value lands in an instance variable of the same name. A dry type is called,
+    # so it coerces as well as checks: `Types::Params::Integer` turns the string a request param
+    # arrives as into an Integer. Anything else that answers `call` is called the same way, and
+    # anything that does not, such as a plain class, is matched with `===`.
+    #
+    # The initializer it builds takes real keywords, so auto render hands a view the props it
+    # declares and drops every other param, the same as it does for a hand written `initialize`.
+    #
+    # Literal needs none of this. Extend `Literal::Properties` instead if you would rather use it.
+    #
+    # @example
+    #   class Card < Phlex::Hanami::Component
+    #     include Phlex::Hanami::Props
+    #
+    #     prop :post, Types::Instance(Post)
+    #     prop :count, Types::Params::Integer
+    #     prop :compact, Types::Bool, default: false
+    #     prop :tags, Types::Array.of(Types::String), default: -> { [] }
+    #
+    #     def view_template
+    #       article(class: ("compact" if @compact)) { h2 { @post.title } }
+    #     end
+    #   end
+    #
+    # @api public
+    # @since 0.3.0
+    module Props
+      # Stands in for a keyword the caller left out, since `nil` can be a real value.
+      #
+      # @api private
+      # @since 0.3.0
+      UNSET = ::Object.new.freeze #: Object
+
+      # How the generated initializer names {UNSET}.
+      #
+      # @api private
+      # @since 0.3.0
+      UNSET_PATH = "::Phlex::Hanami::Props::UNSET" #: String
+
+      # A prop name has to be a Ruby identifier, because it becomes a keyword and an instance
+      # variable.
+      #
+      # @api private
+      # @since 0.3.0
+      NAME_FORMAT = /\A[a-z_][a-zA-Z0-9_]*\z/ #: Regexp
+
+      # Sets each prop's instance variable from the keywords the generated initializer received.
+      #
+      # @api private
+      # @since 0.3.0
+      #: (untyped, Binding) -> void
+      def self.assign(view, arguments)
+        view.class.props.each_value do |prop|
+          value = prop.resolve(view.class, arguments.local_variable_get(prop.name))
+          view.instance_variable_set(:"@#{prop.name}", value)
+        end
+      end
+
+      # @api private
+      # @since 0.3.0
+      #: (Module) -> void
+      def self.included(view_class)
+        view_class.extend(ClassMethods)
+      end
+
+      # @api public
+      # @since 0.3.0
+      module ClassMethods
+        # Declares a prop.
+        #
+        # A prop with a default is optional. So is one whose dry type carries its own, as
+        # `Types::Bool.default(false)` does. A default goes through the type like any other value.
+        # Pass a proc for anything mutable, so each instance gets its own.
+        #
+        # @param name [Symbol] the keyword, and the instance variable the value lands in
+        # @param type [#call, #===] a dry type, or anything that answers `call` or `===`
+        # @param default [Object, Proc] the value when the keyword is left out
+        #
+        # @return [Symbol] the name
+        #
+        # @raise [ArgumentError] if the name is not a Ruby identifier
+        #
+        # @api public
+        # @since 0.3.0
+        #: (Symbol, untyped, ?default: untyped) -> Symbol
+        def prop(name, type, default: UNSET)
+          raise ArgumentError, "#{name.inspect} is not a valid prop name" unless NAME_FORMAT.match?(name.to_s)
+
+          own_props[name] = Prop.new(name, type, default)
+          define_props_initializer
+          name
+        end
+
+        # Every prop this class declares, its superclasses' first.
+        #
+        # @api public
+        # @since 0.3.0
+        #: () -> Hash[Symbol, Prop]
+        def props
+          inherited = superclass.respond_to?(:props) ? superclass.props : {} #: Hash[Symbol, Prop]
+          inherited.merge(own_props)
+        end
+
+        private
+
+        # Writes `initialize` into a module of its own rather than onto the class, so a class can
+        # still define `initialize` and call `super`.
+        #: () -> void
+        def define_props_initializer
+          @props_initializer ||= ::Module.new.tap { |initializer| include(initializer) }
+          keywords = props.each_value.map { |prop| prop.optional? ? "#{prop.name}: #{UNSET_PATH}" : "#{prop.name}:" }
+          signature = keywords.join(", ")
+
+          # `binding` rather than the names themselves, because a prop may be named after a
+          # reserved word such as `class`, which is a valid keyword but not a readable variable.
+          @props_initializer.module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            def initialize(#{signature})                     # def initialize(post:, compact: ::Phlex::Hanami::Props::UNSET)
+              ::Phlex::Hanami::Props.assign(self, binding)  #   ::Phlex::Hanami::Props.assign(self, binding)
+            end                                             # end
+          RUBY
+        end
+
+        #: () -> Hash[Symbol, Prop]
+        def own_props
+          @own_props ||= {}
+        end
+      end
+
+      # One declared prop.
+      #
+      # @api private
+      # @since 0.3.0
+      class Prop
+        attr_reader :name #: Symbol
+
+        #: (Symbol, untyped, untyped) -> void
+        def initialize(name, type, default)
+          @name = name
+          @type = type
+          @default = default
+        end
+
+        # Whether the keyword can be left out.
+        #
+        #: () -> bool
+        def optional?
+          !UNSET.equal?(@default) || type_default?
+        end
+
+        # The value to assign, given what the caller passed or {UNSET}.
+        #
+        # @raise [InvalidPropError] if the type rejects the value
+        #
+        #: (Module, untyped) -> untyped
+        def resolve(view_class, value)
+          if UNSET.equal?(value)
+            return @type.call if UNSET.equal?(@default)
+
+            value = @default.is_a?(::Proc) ? @default.call : @default
+          end
+
+          cast(view_class, value)
+        end
+
+        private
+
+        #: (Module, untyped) -> untyped
+        def cast(view_class, value)
+          if @type.respond_to?(:call)
+            begin
+              return @type.call(value)
+            rescue StandardError => e
+              raise InvalidPropError.new(view_class, @name, e.message)
+            end
+          end
+
+          return value if @type === value # rubocop:disable Style/CaseEquality
+
+          raise InvalidPropError.new(view_class, @name, "#{value.inspect} is not a #{@type.inspect}")
+        end
+
+        # A dry type built with `.default` fills in a missing value itself.
+        #: () -> bool
+        def type_default?
+          @type.respond_to?(:default?) && @type.default?
+        end
+      end
+    end
+  end
+end

data/sig/phlex/hanami/errors/invalid_prop_error.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/phlex/hanami/errors/invalid_prop_error.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class InvalidPropError < Error
+      def initialize: (Module, Symbol, String) -> void
+    end
+  end
+end

data/sig/phlex/hanami/props.rbs

@@ -0,0 +1,45 @@
+# Generated from lib/phlex/hanami/props.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Props
+      UNSET: Object
+
+      UNSET_PATH: String
+
+      NAME_FORMAT: Regexp
+
+      def self.assign: (untyped, Binding) -> void
+
+      def self.included: (Module) -> void
+
+      module ClassMethods
+        def prop: (Symbol, untyped, ?default: untyped) -> Symbol
+
+        def props: () -> Hash[Symbol, Prop]
+
+        private
+
+        def define_props_initializer: () -> void
+
+        def own_props: () -> Hash[Symbol, Prop]
+      end
+
+      class Prop
+        attr_reader name: Symbol
+
+        def initialize: (Symbol, untyped, untyped) -> void
+
+        def optional?: () -> bool
+
+        def resolve: (Module, untyped) -> untyped
+
+        private
+
+        def cast: (Module, untyped) -> untyped
+
+        def type_default?: () -> bool
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-hanami
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Aaron Allen
@@ -68,6 +68,7 @@ files:
 - lib/phlex/hanami/context.rb
 - lib/phlex/hanami/contextual.rb
 - lib/phlex/hanami/errors/error.rb
+- lib/phlex/hanami/errors/invalid_prop_error.rb
 - lib/phlex/hanami/errors/mailer_view_error.rb
 - lib/phlex/hanami/errors/missing_context_error.rb
 - lib/phlex/hanami/errors/relative_path_error.rb
@@ -80,6 +81,7 @@ files:
 - lib/phlex/hanami/mailer/renderable.rb
 - lib/phlex/hanami/mailer/text.rb
 - lib/phlex/hanami/mailer/view.rb
+- lib/phlex/hanami/props.rb
 - lib/phlex/hanami/renderable.rb
 - lib/phlex/hanami/rspec.rb
 - lib/phlex/hanami/slice_configured.rb
@@ -96,6 +98,7 @@ files:
 - sig/phlex/hanami/context.rbs
 - sig/phlex/hanami/contextual.rbs
 - sig/phlex/hanami/errors/error.rbs
+- sig/phlex/hanami/errors/invalid_prop_error.rbs
 - sig/phlex/hanami/errors/mailer_view_error.rbs
 - sig/phlex/hanami/errors/missing_context_error.rbs
 - sig/phlex/hanami/errors/relative_path_error.rbs
@@ -108,6 +111,7 @@ files:
 - sig/phlex/hanami/mailer/renderable.rbs
 - sig/phlex/hanami/mailer/text.rbs
 - sig/phlex/hanami/mailer/view.rbs
+- sig/phlex/hanami/props.rbs
 - sig/phlex/hanami/renderable.rbs
 - sig/phlex/hanami/rspec.rbs
 - sig/phlex/hanami/slice_configured.rbs