view_component-props 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43f3079e4018e9a3be12b0fb7f5be91bbdc1c7cfaf374ad95b03f8a498752d9b
-  data.tar.gz: 4e474c4a200df4766acae82ca46b0f165a8d1f3576f0e0acb9377369ccb076eb
+  metadata.gz: f80ece3769d7472183a42e86a7fc2a37264f5c59b8131d25f9294d6d64f49fae
+  data.tar.gz: e95f39dfd49633c8ed3a32ae61c09ceba1cd06c48dccda877a54017dc45c440d
 SHA512:
-  metadata.gz: 38a4e165b9da70823b05c2189f947f30ffb3497a129f4d4d5db517db0c3956a741956b97b835ee9055d1005ac61697b0acaf0c9fee3b9e49b55e5f3befa077e1
-  data.tar.gz: 67c7850c68584f7f2773cf3f885c1596a3f34131a72ebfefb5193609ef36d287ee996290ff861c764a64ae49adb62ae2fb051d9b1d7d06a08069b525f5ca1270
+  metadata.gz: 057e8e1859b94a01f253211516527f3593d840dfdbb50db30832c24b68965bcf966cf2a0fa35b27443fb54a40d25c1ff90f5a8dd7dc6b990d5fa184981ef90bf
+  data.tar.gz: f01e9685447e35ae07715326302abf184e626dc3e39e1ecc151a5ab4282d54eecc6c331cb7265bdd95eb45e9ab34573e1f863b3f6d151cb259a754da019071b7

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [X.X.X] - YYYY-MM-DD
 
+## [0.0.1] - 2026-05-29
+
+### Added
+
+- `prop` DSL with `default`, `fallback`, `required`, `cast`, `enum`, `validate`, and `description` options
+- Resolved `props` (frozen indifferent hash) and `raw_props` on each instance; `prop_definitions` on the component class for introspection
+- Built-in casters: `:integer`, `:float`, `:string`, `:symbol`, `:boolean`, `:array`, `:hash`, `:decimal`, `:date`, `:datetime`
+- `ViewComponentProps.configure` for global settings and `register_caster` for custom or overriding casters
+- Auto-install into `ViewComponent::Base` (Rails Railtie after initializers, or on require outside Rails); `#initialize` accepts a props hash and invokes `#after_initialize` after resolution
+- Global `reject_undefined_props` configuration and per-class `reject_undefined_props!` / `permit_undefined_props!`
+- `ViewComponentProps.install!` for patching additional base classes outside `ViewComponent::Base`
+- Typed errors under `ViewComponentProps::Error` (`UnknownOptionError`, `UnknownCastError`, `CastError`, `RequiredPropError`, `InvalidEnumValueError`, `ValidationFailedError`, `UnknownPropsError`)
+
 ## [0.0.0] - 2026-05-20
 
 - Initial repository scaffolding and gem publication. No functionality yet.

data/README.md

@@ -1,14 +1,17 @@
-# ViewComponent::Props
+# ViewComponentProps
 
-A [ViewComponent](https://viewcomponent.org) extension for working with component props.
+A [ViewComponent](https://viewcomponent.org) extension that adds a `prop` DSL to components: defaults, fallbacks, required props, casting, enum validation, custom validators, and a pluggable caster registry.
 
-> [!NOTE]
-> This gem is in early development. The public API is not yet stable and there is no usable functionality in this release. Documentation and examples will land alongside the first feature release.
+In Rails apps, a Railtie patches `ViewComponent::Base` during boot (enabled by default). Outside Rails, the gem patches on require. Inherit as usual and pass a props hash to `new`.
 
 ## Requirements
 
 - Ruby >= 3.0
-- ViewComponent >= 3.0
+- [ViewComponent](https://viewcomponent.org) >= 3.0, < 5.0
+- ActiveSupport >= 6.0, < 9.0
+- ActiveModel >= 6.0, < 9.0
+
+Rails is supported via a Railtie but not required; the gem auto-installs into `ViewComponent::Base` on require when Rails is not loaded.
 
 ## Installation
 
@@ -26,7 +29,151 @@ bundle install
 
 ## Usage
 
-Coming soon.
+```ruby
+class ButtonComponent < ViewComponent::Base
+  CLASS = %w[
+    px-9
+    py-3
+    text-lg
+    font-medium
+    tracking-wider
+    ring-0
+  ].freeze
+
+  prop :label, required: true
+  prop :shape, cast: :symbol, enum: %i[pill rounded rectangle], default: :pill
+  prop :disabled, cast: :boolean, default: false
+
+  def before_render
+    @class = cn(CLASS, {
+      "rounded-full" => @props[:shape] == :pill,
+      "rounded-xl" => @props[:shape] == :rounded,
+      "rounded-none" => @props[:shape] == :rectangle,
+    }, @props[:class])
+  end
+
+  def call
+    tag.button(@props[:label], class: @class, disabled: @props[:disabled])
+  end
+end
+
+render ButtonComponent.new(label: "Save", shape: :rounded)
+```
+
+Resolved props are available as `props` (or `@props`), a frozen hash you can read with either string or symbol keys. The original input, before any casting or defaults are applied, is available as `raw_props` (or `@raw_props`).
+
+Once props are resolved, `#after_initialize` runs, so you can override it for any setup that depends on `props`.
+
+### Options
+
+Each `prop` accepts:
+
+| Option         | Purpose                                                          |
+| -------------- | ---------------------------------------------------------------- |
+| `default:`     | Value (or callable) used when the key is missing from the input. |
+| `fallback:`    | Value (or callable) used when the resolved value is `nil`.       |
+| `required:`    | Raises `RequiredPropError` when the resolved value is `nil`.     |
+| `cast:`        | Coerces the value. A built-in caster name or any callable.       |
+| `enum:`        | Restricts the value to a list of allowed values.                 |
+| `validate:`    | Callable that must return truthy for the value to be accepted.   |
+| `description:` | Free-form string for documentation and tooling.                  |
+
+Defaults and fallbacks can also be callables, evaluated in the context of the component instance. Use `raw_props` to read other props from the constructor input:
+
+```ruby
+class AvatarComponent < ViewComponent::Base
+  prop :user, required: true
+  prop :alt, default: -> { "#{raw_props[:user].name}'s avatar" }
+end
+```
+
+### Casters
+
+Built-in casters: `:integer`, `:float`, `:string`, `:symbol`, `:boolean`, `:array`, `:hash`, `:decimal`, `:date`, `:datetime`.
+
+A `nil` value is never cast and stays `nil`. Use `default:` or `fallback:` when you need a value for a missing or `nil` prop.
+
+Register custom casters in the configuration block:
+
+```ruby
+ViewComponentProps.configure do |config|
+  config.register_caster(:slug) do |value|
+    value.to_s.parameterize
+  end
+end
+
+class HeadingComponent < ViewComponent::Base
+  prop :anchor, cast: :slug
+end
+```
+
+Built-in casters can be overridden the same way by registering the same key again in `configure`.
+
+Or pass a lambda inline:
+
+```ruby
+prop :code, cast: ->(value) { value.to_s.upcase }
+```
+
+### Strict props
+
+```ruby
+class FormFieldComponent < ViewComponent::Base
+  reject_undefined_props!
+
+  prop :name, required: true
+  prop :label
+end
+
+FormFieldComponent.new(name: "email", typo: true)
+# => raises ViewComponentProps::UnknownPropsError
+```
+
+### Custom base classes
+
+`ViewComponentProps.install!(MyComponentBase)` applies the same patch to another class (idempotent). Useful if your app uses a shared component superclass that does **not** inherit from `ViewComponent::Base`.
+
+`install!` no-ops when the target already includes `Definable` through any ancestor, so calling it on a subclass of `ViewComponent::Base` does nothing (the patch is already inherited). You only need it for base classes outside the `ViewComponent::Base` hierarchy.
+
+## Configuration
+
+### Rails
+
+Disable auto-install in `config/application.rb`:
+
+```ruby
+config.view_component_props.auto_include = false
+```
+
+When enabled (the default), `ViewComponent::Base` is patched after initializers load so `config/initializers` can configure the gem first.
+
+### Initializer
+
+```ruby
+ViewComponentProps.configure do |config|
+  config.reject_undefined_props = true
+
+  config.register_caster(:slug) do |value|
+    value.to_s.parameterize
+  end
+end
+```
+
+When `reject_undefined_props` is `true`, every component rejects unknown prop keys by default. Override per class with `reject_undefined_props!` or `permit_undefined_props!`.
+
+### Non-Rails
+
+Auto-install runs on require when `configuration.auto_include` is `true` (the default). Because it is read at require time, you must configure it **before** requiring the gem for it to have any effect:
+
+```ruby
+require "view_component_props/configuration"
+ViewComponentProps.configure { |config| config.auto_include = false }
+
+require "view_component_props"
+ViewComponentProps.install!
+```
+
+Configuring `auto_include` _after_ `require "view_component_props"` cannot reverse the install that already happened. Note this `configuration.auto_include` switch is consulted only outside Rails; in Rails the equivalent switch is `config.view_component_props.auto_include`, handled by the Railtie.
 
 ## Development
 

data/lib/view_component_props/casters/base.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ViewComponentProps
+  module Casters
+    class Base
+      BOOLEAN_TYPE = ActiveModel::Type::Boolean.new
+
+      class_attribute :base_casters, instance_accessor: false, default: HashWithIndifferentAccess.new
+
+      def self.register_caster(key, &block)
+        Casters.registry[key] = block
+        self.base_casters = base_casters.merge(key => block)
+      end
+
+      register_caster(:integer) do |value|
+        Integer(value)
+      end
+
+      register_caster(:float) do |value|
+        Float(value)
+      end
+
+      register_caster(:string) do |value|
+        value.to_s
+      end
+
+      register_caster(:symbol) do |value|
+        value.to_sym
+      end
+
+      register_caster(:boolean) do |value|
+        BOOLEAN_TYPE.cast(value)
+      end
+
+      register_caster(:array) do |value|
+        Array(value)
+      end
+
+      register_caster(:hash) do |value|
+        value.is_a?(Hash) ? value : value.to_h
+      end
+
+      register_caster(:decimal) do |value|
+        value.is_a?(BigDecimal) ? value : BigDecimal(value.to_s)
+      end
+
+      register_caster(:date) do |value|
+        value.is_a?(Date) ? value : Date.parse(value.to_s)
+      end
+
+      register_caster(:datetime) do |value|
+        if value.is_a?(Time) || value.is_a?(DateTime)
+          value
+        else
+          Time.zone ? Time.zone.parse(value.to_s) : Time.parse(value.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/view_component_props/casters.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/module/attribute_accessors"
+require "bigdecimal"
+require "date"
+require "time"
+require "active_model"
+require "active_model/type"
+require "active_model/type/boolean"
+
+require_relative "configuration"
+
+module ViewComponentProps
+  module Casters
+    mattr_accessor :registry, default: HashWithIndifferentAccess.new
+
+    class << self
+      def fetch(key)
+        registry.fetch(key)
+      end
+
+      def known?(key)
+        registry.key?(key)
+      end
+
+      def reset!
+        self.registry = Base.base_casters.merge(ViewComponentProps.configuration.custom_casters)
+      end
+    end
+  end
+end
+
+require_relative "casters/base"
+
+ViewComponentProps::Casters.reset!

data/lib/view_component_props/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+
+module ViewComponentProps
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      Casters.reset! if defined?(Casters)
+    end
+  end
+
+  class Configuration
+    attr_accessor :auto_include
+    attr_accessor :reject_undefined_props
+    attr_reader :custom_casters
+
+    def initialize
+      @auto_include = true
+      @reject_undefined_props = false
+      @custom_casters = HashWithIndifferentAccess.new
+    end
+
+    def register_caster(key, &block)
+      raise ArgumentError, "register_caster requires a block" unless block
+
+      custom_casters[key] = block
+      Casters.registry[key] = block if defined?(Casters)
+    end
+  end
+end

data/lib/view_component_props/definable.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ViewComponentProps
+  module Definable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :prop_definitions, instance_accessor: false, default: HashWithIndifferentAccess.new
+      class_attribute :undefined_props_rejected, instance_accessor: false, default: nil
+
+      attr_reader :props
+      attr_reader :raw_props
+    end
+
+    class_methods do
+      def prop(key, options = {})
+        definition = Definition.new(key, options, component: name)
+        self.prop_definitions = prop_definitions.merge(key => definition)
+      end
+
+      def reject_undefined_props!
+        self.undefined_props_rejected = true
+      end
+
+      def permit_undefined_props!
+        self.undefined_props_rejected = false
+      end
+    end
+
+    def setup_props_for(props)
+      enforce_defined_props!(props) if undefined_props_rejected?
+
+      indifferent_props = props.with_indifferent_access
+      @raw_props = props.dup.freeze
+      @props = resolve_props(indifferent_props).freeze
+    end
+
+    def after_initialize; end
+
+    private
+
+    def undefined_props_rejected?
+      per_class_setting = self.class.undefined_props_rejected
+      return per_class_setting unless per_class_setting.nil?
+
+      ViewComponentProps.configuration.reject_undefined_props
+    end
+
+    def enforce_defined_props!(props)
+      declared_props = self.class.prop_definitions.keys.map(&:to_s)
+      unknown_props = props.keys.map(&:to_s) - declared_props
+      return if unknown_props.empty?
+
+      raise UnknownPropsError, "Unknown props for #{self.class.name}: #{unknown_props.map(&:to_sym).inspect}"
+    end
+
+    def resolve_props(props)
+      self.class.prop_definitions.each_with_object(props.dup) do |(key, definition), resolved|
+        resolved[key] = definition.call(props, self)
+      end
+    end
+  end
+end

data/lib/view_component_props/definition.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module ViewComponentProps
+  class Definition
+    OPTION_KEYS = %i[
+      default
+      fallback
+      required
+      cast
+      enum
+      validate
+      description
+    ].freeze
+
+    attr_reader :key, :description
+
+    def initialize(key, options = {}, component:)
+      @key = key
+      @options = options
+      @component = component
+
+      validate_options!
+
+      cast = normalize_cast(@options[:cast])
+      @caster = build_caster(cast)
+      @cast_label = describe_cast(cast)
+      @required = @options[:required] || false
+      @enum = @options[:enum]
+      @validate = @options[:validate]
+      @default = @options[:default]
+      @fallback = @options[:fallback]
+      @description = @options[:description]
+    end
+
+    def call(props, instance = nil)
+      value = evaluate(props, instance)
+      casted_value = cast_value(value)
+
+      raise RequiredPropError, "Required prop :#{@key} for #{@component} cannot be nil" if casted_value.nil? && @required
+      return casted_value if casted_value.nil?
+
+      raise InvalidEnumValueError, "Prop :#{@key} for #{@component} must be one of #{@enum.inspect}, got #{casted_value.inspect}" if @enum && !@enum.include?(casted_value)
+      raise ValidationFailedError, "Prop :#{@key} for #{@component} failed validation, got #{casted_value.inspect}" if @validate && !@validate.call(casted_value)
+
+      casted_value
+    end
+
+    private
+
+    def validate_options!
+      unknown_keys = @options.keys - OPTION_KEYS
+      raise UnknownOptionError, "Unknown options for prop :#{@key}: #{unknown_keys.inspect}" if unknown_keys.any?
+
+      return unless @options.key?(:cast)
+
+      cast_option = @options[:cast]
+      raise UnknownCastError, "Cast type for prop :#{@key} cannot be nil" if cast_option.nil?
+      return if cast_option.respond_to?(:call)
+      return if cast_option.is_a?(Symbol) || cast_option.is_a?(String)
+
+      raise UnknownCastError, "Cast type for prop :#{@key} must be a Symbol, String, or callable, got #{cast_option.inspect}"
+    end
+
+    def normalize_cast(value)
+      return nil if value.nil?
+      return value if value.respond_to?(:call)
+
+      value.to_sym
+    end
+
+    def evaluate(props, instance)
+      props = props.with_indifferent_access unless props.is_a?(HashWithIndifferentAccess)
+      value = begin
+        if props.key?(@key)
+          props[@key]
+        elsif @options.key?(:default)
+          resolve(@default, instance)
+        end
+      end
+
+      value = resolve(@fallback, instance) if value.nil? && @options.key?(:fallback)
+      value
+    end
+
+    def build_caster(cast)
+      return nil if cast.nil?
+      return cast if cast.respond_to?(:call)
+
+      ->(value) { Casters.fetch(cast).call(value) }
+    end
+
+    def cast_value(value)
+      return value if value.nil? || @caster.nil?
+
+      @caster.call(value)
+    rescue ViewComponentProps::Error
+      raise
+    rescue ArgumentError, TypeError, NoMethodError, KeyError, RangeError => e
+      raise CastError, "Prop :#{@key} for #{@component} could not be cast to #{@cast_label} (got #{value.inspect}): #{e.message}"
+    end
+
+    def describe_cast(cast)
+      return nil if cast.nil?
+      return cast.inspect unless cast.respond_to?(:call)
+
+      location = cast.respond_to?(:source_location) ? cast.source_location : nil
+      location ? "callable at #{location.join(':')}" : "callable"
+    end
+
+    def resolve(value, instance)
+      return value unless value.respond_to?(:call)
+
+      instance ? instance.instance_exec(&value) : value.call
+    end
+  end
+end

data/lib/view_component_props/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ViewComponentProps
+  class Error < StandardError; end
+
+  class UnknownOptionError < Error; end
+  class UnknownCastError < Error; end
+  class CastError < Error; end
+  class RequiredPropError < Error; end
+  class InvalidEnumValueError < Error; end
+  class ValidationFailedError < Error; end
+  class UnknownPropsError < Error; end
+end

data/lib/view_component_props/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ViewComponentProps
+  class Railtie < Rails::Railtie
+    config.view_component_props = ActiveSupport::OrderedOptions.new
+    config.view_component_props.auto_include = true
+
+    initializer "view_component_props.install", after: :load_config_initializers do |application|
+      ViewComponentProps.install! if application.config.view_component_props.auto_include
+    end
+  end
+end

data/lib/view_component_props/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ViewComponentProps
+  VERSION = "0.0.1"
+end

data/lib/view_component_props.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/hash/indifferent_access"
+require "view_component"
+
+require_relative "view_component_props/configuration"
+require_relative "view_component_props/errors"
+require_relative "view_component_props/casters"
+require_relative "view_component_props/definition"
+require_relative "view_component_props/definable"
+require_relative "view_component_props/version"
+
+module ViewComponentProps
+  class << self
+    def install!(target = ViewComponent::Base)
+      return if target.include?(Definable)
+
+      target.include(Definable)
+      target.class_eval do
+        def initialize(props = {})
+          super()
+          setup_props_for(props)
+          after_initialize
+        end
+      end
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require_relative "view_component_props/railtie"
+elsif ViewComponentProps.configuration.auto_include
+  ViewComponentProps.install!
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_component-props
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Kinnell Shah
@@ -9,6 +9,26 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -49,8 +69,10 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: 'A ViewComponent extension for working with component props. Functionality
-  is in active development.
+description: 'A ViewComponent extension that adds a `prop` DSL with defaults, fallbacks,
+  required props, casting, enum validation, custom validators, and a pluggable caster
+  registry. Patches ViewComponent::Base via a Rails Railtie (or on require outside
+  Rails) so components accept a props hash out of the box.
 
   '
 email:
@@ -62,10 +84,15 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- lib/view_component/props.rb
-- lib/view_component/props/configuration.rb
-- lib/view_component/props/errors.rb
-- lib/view_component/props/version.rb
+- lib/view_component_props.rb
+- lib/view_component_props/casters.rb
+- lib/view_component_props/casters/base.rb
+- lib/view_component_props/configuration.rb
+- lib/view_component_props/definable.rb
+- lib/view_component_props/definition.rb
+- lib/view_component_props/errors.rb
+- lib/view_component_props/railtie.rb
+- lib/view_component_props/version.rb
 homepage: https://github.com/kinnell/view_component-props
 licenses:
 - MIT

data/lib/view_component/props/configuration.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module ViewComponent
-  module Props
-    class Configuration # rubocop:disable Lint/EmptyClass
-    end
-  end
-end

data/lib/view_component/props/errors.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module ViewComponent
-  module Props
-    class Error < StandardError; end
-  end
-end

data/lib/view_component/props/version.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module ViewComponent
-  module Props
-    VERSION = "0.0.0"
-  end
-end

data/lib/view_component/props.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/concern"
-require "active_support/dependencies/autoload"
-require "active_support/core_ext/hash/indifferent_access"
-require "view_component"
-
-require_relative "props/configuration"
-require_relative "props/errors"
-require_relative "props/version"
-
-module ViewComponent
-  module Props
-    extend ActiveSupport::Concern
-    extend ActiveSupport::Autoload
-
-    class << self
-      def configuration
-        @configuration ||= Configuration.new
-      end
-
-      def configure
-        yield(configuration)
-      end
-
-      def reset_configuration!
-        @configuration = Configuration.new
-      end
-    end
-  end
-end