phlex-hanami 0.2.0.pre.alpha.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4adab6a5900c422ff7da10ee21be828ba77c1d7523da39173433ff7749516e73
-  data.tar.gz: d44d102a14b331b1262f692f8479418d8f08557815830899c3fb9be093f34e25
+  metadata.gz: 301d34d14bd2989ab0ab899fd6f76e38b5a8e8b1a3fcffa182f6ece292652e81
+  data.tar.gz: 74e00aebe59f62800ad37bd576ab97f71efbfbabb536d5fa115e8b2ce5789509
 SHA512:
-  metadata.gz: 151ad52da0f7b28599a61385974233e109be3a195710f3d2d971783c25202d830cc04b7d85fb8f19c90c6058c2798f0f8e85bc4bc3a81d86003ec242884fb939
-  data.tar.gz: 85e34fbfb79b7cb58352575c5d1cdb18066f4034a427a3d55753992b7f5653d3a348e27c98f593b5db2f56f711fc90755965d5c0470a74f0b467192f6368c833
+  metadata.gz: 84d0aec75d54b2e1e7be95d57c9d2c7e9afb560abd4ec7b86065136618775988a33776da0195c71222f9921c628c7b3b6168ca8cc84710f8a18709114210d6a6
+  data.tar.gz: 8ab7a57fac797d8daa565d6335ed9efbe2b1cfde7c0f67f30ab98a5c8c01341ee6a2b46ebb0eced44807084080fc6f5d73bec15914f16780163143f4b1b13cc3

data/CHANGELOG.md

@@ -7,6 +7,48 @@ 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
+to a new gem and start from the [usage docs](https://github.com/aaronmallen/phlex-hanami/tree/main/docs/usage). The
+alpha sections below record each change as it landed. This section gathers them in one place.
+
+### Added
+
+- `Phlex::Hanami::View` and `Phlex::Hanami::Layout`, the base classes for a view and a layout, and
+  `Phlex::Hanami::Renderable` for a `Phlex::HTML` base class you already have.
+- Auto render. An action renders the Phlex view whose container key matches its own, so
+  `MyApp::Actions::Posts::Index` renders `MyApp::Views::Posts::Index` with no `response.render` call and no
+  configuration. An action with no matching view renders nothing, so a slice can move to Phlex one action at a time.
+- A view receives the exposures and params its `initialize` asks for and drops the rest, so a stray query param does
+  not raise. An initializer that takes `**` receives all of it.
+- A layout convention: `Views::Layout` in a slice wraps that slice's views. `layout` sets a different one, and
+  `layout nil` opts out. The view renders before its layout, so a `content_for` set in the view shows up in the
+  layout's `head`.
+- The view context in every view and every component under it: `path`, `url`, `asset_url`, `content_for`,
+  `csrf_token`, `flash`, `session`, `request` and more. A view reads the same whether or not hanami-view is bundled.
+- `t`, which resolves a relative key against the view's container key, so `t(".title")` in
+  `MyApp::Views::Posts::Index` looks up `posts.index.title`.
+- `Phlex::Hanami::Helpers`, an opt in for Hanami's helper library, such as `form_for` and `format_number`. It needs
+  hanami-view. Their output renders as markup rather than escaped twice, and Phlex keeps its own `raw` and `tag`.
+- `Phlex::Hanami::Component` for everything below a view, `Phlex::Hanami::Contextual` for a component base class you
+  already have, and support for [Phlex kits](https://www.phlex.fun/components/kits.html).
+- Phlex views for [hanami-mailer](https://github.com/hanami/mailer), through `Phlex::Hanami::Mailer::View` and
+  `Phlex::Hanami::Mailer::Layout`. A mailer renders the view whose container key matches its own, and the gem builds
+  the plain text part from the HTML unless the view defines `text_body`.
+- `Phlex::Hanami::Testing::ViewHelpers`, for testing a view or a component without a request, and
+  `require "phlex/hanami/rspec"` to include them in every example group tagged `type: :view`.
+- RBS signatures for the public API, shipped in `sig`.
+- Usage docs for every part of the gem, including how it hooks into Hanami and why code reloading needs no extra
+  work.
+
 ## [v0.2.0-alpha.3] - 2026-09-06
 
 ### Added
@@ -66,7 +108,8 @@ Initial alpha release by the new maintainer [@aaronmallen](https://github.com/aa
 
 Initial release, by the previous maintainer [@stephannv](https://github.com/stephannv).
 
-[Unreleased]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.3...HEAD
+[Unreleased]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0...HEAD
+[v0.2.0]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.3...0.2.0
 [v0.2.0-alpha.3]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.2...0.2.0-alpha.3
 [v0.2.0-alpha.2]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.1...0.2.0-alpha.2
 [v0.2.0-alpha.1]: https://github.com/aaronmallen/phlex-hanami/releases/tag/0.2.0-alpha.1

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.pre.alpha.3
+  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