view_component_devtools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21babb25c8660808d7564914dd2105566e39e9954a197643e7862815ea867583
+  data.tar.gz: c64e1042bef475216ff30b64d7fc8f5ac16d308524bb916d2460ef3a9d3e75a9
+SHA512:
+  metadata.gz: f88cbecd121cc209eb6dd9e2a82e792cf1f7636becbc183ab6ea490cf563af7b3318d86246bce203780f79465ad5f457047ad348704732185d3ce952109fded6
+  data.tar.gz: e9420245c4fdad743a6cec795c2e2c8846d247181436ec3bc0d41f4a1868dc0c793a745f0744be4f565e31976ff5a7a3b70d0ac69a49ebd6c97b271b2727d1d2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ViewComponent DevTools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+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 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.

data/README.md

@@ -0,0 +1,9 @@
+# view_component_devtools gem
+
+Development-only Rails instrumentation for the ViewComponent DevTools browser
+panel. The gem subscribes to ViewComponent's native ActiveSupport notification,
+stores a bounded render tree in request-local state, and exposes it through an
+explicit layout helper.
+
+See the repository [README](../../README.md) for installation, configuration,
+security behavior, and the browser extension setup.

data/lib/view_component_devtools/component.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ViewComponentDevtools
+  module Component
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def devtools_props(*names)
+        @view_component_devtools_props ||= []
+        @view_component_devtools_props.concat(names.map(&:to_sym)).uniq!
+      end
+
+      def view_component_devtools_prop_names
+        inherited = superclass.respond_to?(:view_component_devtools_prop_names) ?
+          superclass.view_component_devtools_prop_names : []
+        initializer_names = instance_method(:initialize).parameters.filter_map do |kind, name|
+          name if %i[req opt keyreq key].include?(kind)
+        end
+        declared = @view_component_devtools_props || []
+        trusted = inherited + declared
+
+        (trusted + initializer_names).uniq.select do |name|
+          prop_reader?(name, trusted: trusted.include?(name))
+        end
+      end
+
+      private
+
+      def prop_reader?(name, trusted:)
+        return false unless public_method_defined?(name)
+
+        method = instance_method(name)
+        callable_without_arguments = method.parameters.none? do |kind, _|
+          %i[req keyreq].include?(kind)
+        end
+        callable_without_arguments && (trusted || component_class_owner?(method.owner))
+      end
+
+      def component_class_owner?(owner)
+        return false unless owner.is_a?(Class)
+
+        if defined?(ViewComponent::Base) && self < ViewComponent::Base
+          owner < ViewComponent::Base
+        else
+          self <= owner
+        end
+      end
+    end
+
+    def render_in(...)
+      return super unless State.active?
+
+      metadata = {
+        name: self.class.name,
+        source_location: component_source_location,
+        props: self.class.view_component_devtools_prop_names.to_h do |name|
+          [name, public_send(name)]
+        end
+      }
+
+      State.with_component(metadata) { super }
+    end
+
+    private
+
+    def component_source_location
+      if self.class.respond_to?(:identifier)
+        identifier = self.class.identifier
+        return identifier if identifier
+      end
+
+      self.class.instance_method(:initialize).source_location&.join(":")
+    end
+  end
+end

data/lib/view_component_devtools/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ViewComponentDevtools
+  class Configuration
+    DEFAULT_REDACT_KEYS = [
+      /authorization/i,
+      /cookie/i,
+      /credential/i,
+      /passw(or)?d/i,
+      /private.?key/i,
+      /secret/i,
+      /session/i,
+      /token/i
+    ].freeze
+
+    attr_accessor :allow_non_development,
+      :enabled,
+      :max_collection_size,
+      :max_components,
+      :max_depth,
+      :max_string_length,
+      :redact_keys
+
+    def initialize
+      @enabled = false
+      @allow_non_development = false
+      @max_components = 500
+      @max_depth = 8
+      @max_collection_size = 50
+      @max_string_length = 2_000
+      @redact_keys = DEFAULT_REDACT_KEYS.dup
+    end
+
+    def enabled_for?(environment)
+      enabled && (environment.to_s == "development" || allow_non_development)
+    end
+  end
+end

data/lib/view_component_devtools/engine.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module ViewComponentDevtools
+  class Engine < ::Rails::Engine
+    initializer "view_component_devtools.middleware" do |application|
+      application.middleware.use Middleware
+    end
+
+    initializer "view_component_devtools.helper" do
+      ActiveSupport.on_load(:action_view) { include Helper }
+    end
+
+    initializer "view_component_devtools.subscriber" do
+      Subscriber.install!
+    end
+
+    config.after_initialize do
+      next unless ViewComponentDevtools.capture_enabled?
+
+      Rails.application.config.view_component.instrumentation_enabled = true
+      require "view_component/instrumentation"
+      unless ViewComponent::Base < ViewComponent::Instrumentation
+        ViewComponent::Base.prepend(ViewComponent::Instrumentation)
+      end
+    end
+  end
+end

data/lib/view_component_devtools/helper.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/output_safety"
+require "json"
+
+module ViewComponentDevtools
+  module Helper
+    ELEMENT_ID = "view-component-devtools-data"
+
+    def view_component_devtools_payload
+      return "".html_safe unless State.active?
+
+      json = JSON.generate(State.current.payload)
+        .gsub("<", "\\u003c")
+        .gsub(">", "\\u003e")
+        .gsub("&", "\\u0026")
+        .gsub("\u2028", "\\u2028")
+        .gsub("\u2029", "\\u2029")
+
+      %(<script type="application/json" id="#{ELEMENT_ID}" data-version="1">#{json}</script>).html_safe
+    end
+  end
+end

data/lib/view_component_devtools/middleware.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rack/body_proxy"
+
+module ViewComponentDevtools
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(environment)
+      return app.call(environment) unless ViewComponentDevtools.capture_enabled?
+
+      State.start!(request_id: environment["action_dispatch.request_id"] || environment["HTTP_X_REQUEST_ID"])
+      completed = false
+
+      begin
+        status, headers, body = app.call(environment)
+        response = [status, headers, Rack::BodyProxy.new(body) { State.reset! }]
+        completed = true
+        response
+      ensure
+        State.reset! unless completed
+      end
+    end
+
+    private
+
+    attr_reader :app
+  end
+end

data/lib/view_component_devtools/normalizer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module ViewComponentDevtools
+  class Normalizer
+    REDACTED = "[REDACTED]"
+
+    def initialize(configuration = ViewComponentDevtools.configuration)
+      @configuration = configuration
+    end
+
+    def call(value)
+      normalize(value, depth: 0, ancestors: {})
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def normalize(value, depth:, ancestors:)
+      return "[maximum depth exceeded]" if depth > configuration.max_depth
+
+      case value
+      when nil, true, false, Integer
+        value
+      when Float
+        value.finite? ? value : "[non-finite Float]"
+      when String
+        truncate(sanitize_string(value))
+      when Symbol
+        truncate(sanitize_string(value.to_s))
+      when Time, DateTime
+        value.iso8601(3)
+      when Date
+        value.iso8601
+      when Array
+        normalize_array(value, depth:, ancestors:)
+      when Hash
+        normalize_hash(value, depth:, ancestors:)
+      else
+        "[unsupported #{value.class.name}]"
+      end
+    end
+
+    def normalize_array(value, depth:, ancestors:)
+      with_cycle_guard(value, ancestors) do |next_ancestors|
+        entries = value.first(configuration.max_collection_size).map do |entry|
+          normalize(entry, depth: depth + 1, ancestors: next_ancestors)
+        end
+        entries << "[#{value.length - entries.length} more items]" if value.length > entries.length
+        entries
+      end
+    end
+
+    def normalize_hash(value, depth:, ancestors:)
+      with_cycle_guard(value, ancestors) do |next_ancestors|
+        entries = value.first(configuration.max_collection_size).to_h
+        normalized = entries.each_with_object({}) do |(key, entry), result|
+          original_key = stringify_key(key)
+          next unless original_key
+
+          normalized_key = truncate(original_key)
+          result[normalized_key] = if redact?(original_key)
+            REDACTED
+          else
+            normalize(entry, depth: depth + 1, ancestors: next_ancestors)
+          end
+        end
+        normalized["__truncated__"] = value.length - entries.length if value.length > entries.length
+        normalized
+      end
+    end
+
+    def stringify_key(key)
+      return sanitize_string(key.to_s) if key.is_a?(String) || key.is_a?(Symbol)
+
+      nil
+    end
+
+    def redact?(key)
+      configuration.redact_keys.any? do |pattern|
+        pattern.is_a?(Regexp) ? pattern.match?(key) : key.downcase.include?(pattern.to_s.downcase)
+      end
+    end
+
+    def truncate(value)
+      return value if value.length <= configuration.max_string_length
+
+      "#{value[0, configuration.max_string_length]}…"
+    end
+
+    def sanitize_string(value)
+      value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "�")
+    end
+
+    def with_cycle_guard(value, ancestors)
+      return "[circular reference]" if ancestors.key?(value.object_id)
+
+      yield ancestors.merge(value.object_id => true)
+    end
+  end
+end

data/lib/view_component_devtools/state.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "active_support/isolated_execution_state"
+require "securerandom"
+require "time"
+
+module ViewComponentDevtools
+  module State
+    KEY = :view_component_devtools_session
+
+    class << self
+      def start!(request_id: nil)
+        raise "ViewComponent DevTools capture already active" if active?
+
+        ActiveSupport::IsolatedExecutionState[KEY] = Session.new(
+          request_id: request_id || SecureRandom.uuid,
+          configuration: ViewComponentDevtools.configuration
+        )
+      end
+
+      def current
+        ActiveSupport::IsolatedExecutionState[KEY]
+      end
+
+      def active?
+        !current.nil?
+      end
+
+      def reset!
+        ActiveSupport::IsolatedExecutionState.delete(KEY)
+      end
+
+      def with_component(metadata)
+        return yield unless current
+
+        current.push_component(metadata)
+        yield
+      ensure
+        current&.pop_component(metadata)
+      end
+    end
+
+    class Session
+      attr_reader :request_id
+
+      def initialize(request_id:, configuration:)
+        @request_id = request_id
+        @configuration = configuration
+        @components = []
+        @component_stack = []
+        @event_stack = []
+        @component_count = 0
+        @truncated = false
+        @normalizer = Normalizer.new(configuration)
+      end
+
+      def push_component(metadata)
+        component_stack << metadata
+      end
+
+      def pop_component(metadata)
+        actual = component_stack.pop
+        raise "ViewComponent DevTools component stack mismatch" unless actual.equal?(metadata)
+      end
+
+      def start_event(event_id, payload, start_time)
+        node = build_node(payload, start_time)
+        event_stack << {event_id:, node:}
+        return unless node
+
+        parent = event_stack.reverse_each.drop(1).find { |entry| entry[:node] }&.fetch(:node)
+        (parent ? parent[:children] : components) << node
+      end
+
+      def finish_event(event_id, payload, finish_time)
+        entry = event_stack.pop
+        raise "ViewComponent DevTools event stack mismatch" unless entry&.fetch(:event_id) == event_id
+
+        node = entry[:node]
+        return unless node
+
+        node[:durationMs] = ((finish_time - node.delete(:startedAt)) * 1_000).round(3)
+        node[:templateLocation] = payload[:view_identifier] if payload[:view_identifier]
+      end
+
+      def payload
+        {
+          version: 1,
+          requestId: request_id,
+          generatedAt: Time.now.utc.iso8601(3),
+          truncated: @truncated,
+          components:
+        }
+      end
+
+      private
+
+      attr_reader :component_stack, :components, :configuration, :event_stack, :normalizer
+
+      def build_node(payload, start_time)
+        if @component_count >= configuration.max_components
+          @truncated = true
+          return nil
+        end
+
+        @component_count += 1
+        metadata = component_stack.last
+        metadata = nil unless metadata&.fetch(:name, nil) == payload[:name]
+        {
+          id: "#{request_id}:#{@component_count}",
+          name: payload[:name] || metadata&.fetch(:name, nil) || "AnonymousComponent",
+          sourceLocation: payload[:identifier] || metadata&.fetch(:source_location, nil),
+          templateLocation: payload[:view_identifier],
+          durationMs: nil,
+          props: normalizer.call(metadata&.fetch(:props, {}) || {}),
+          children: [],
+          startedAt: start_time
+        }
+      end
+    end
+  end
+end

data/lib/view_component_devtools/subscriber.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module ViewComponentDevtools
+  class Subscriber
+    EVENT_NAMES = ["render.view_component", "!render.view_component"].freeze
+
+    class << self
+      def install!
+        @install_mutex ||= Mutex.new
+        @install_mutex.synchronize do
+          @subscriptions ||= EVENT_NAMES.map do |event_name|
+            ActiveSupport::Notifications.subscribe(event_name, new)
+          end
+        end
+      end
+    end
+
+    def start(_name, event_id, payload)
+      State.current&.start_event(event_id, payload, monotonic_time)
+    end
+
+    def finish(_name, event_id, payload)
+      State.current&.finish_event(event_id, payload, monotonic_time)
+    end
+
+    private
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/view_component_devtools/version.rb

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

data/lib/view_component_devtools.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "view_component_devtools/version"
+require_relative "view_component_devtools/configuration"
+require "rails"
+require "view_component"
+
+module ViewComponentDevtools
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def capture_enabled?(environment = rails_environment)
+      configuration.enabled_for?(environment)
+    end
+
+    private
+
+    def rails_environment
+      defined?(Rails) && Rails.respond_to?(:env) ? Rails.env : ENV.fetch("RAILS_ENV", "development")
+    end
+  end
+end
+
+require_relative "view_component_devtools/normalizer"
+require_relative "view_component_devtools/state"
+require_relative "view_component_devtools/component"
+require_relative "view_component_devtools/subscriber"
+require_relative "view_component_devtools/middleware"
+require_relative "view_component_devtools/helper"
+require_relative "view_component_devtools/engine"

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: view_component_devtools
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ViewComponent DevTools contributors
+bindir: bin
+cert_chain: []
+date: 2026-08-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+description: Captures a safe ViewComponent render tree for a browser DevTools panel.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/view_component_devtools.rb
+- lib/view_component_devtools/component.rb
+- lib/view_component_devtools/configuration.rb
+- lib/view_component_devtools/engine.rb
+- lib/view_component_devtools/helper.rb
+- lib/view_component_devtools/middleware.rb
+- lib/view_component_devtools/normalizer.rb
+- lib/view_component_devtools/state.rb
+- lib/view_component_devtools/subscriber.rb
+- lib/view_component_devtools/version.rb
+homepage: https://github.com/zaviermiller/view_component_devtools
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zaviermiller/view_component_devtools
+  source_code_uri: https://github.com/zaviermiller/view_component_devtools/tree/main/packages/view_component_devtools
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Development-only component inspection for Rails ViewComponent
+test_files: []