hakumi_components 0.1.18.pre → 0.1.19.pre

data/lib/generators/hakumi_components/install_generator.rb

@@ -1,11 +1,15 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
-  class InstallGenerator < Rails::Generators::Base
+  class InstallGenerator < ::Rails::Generators::Base
+    extend T::Sig
+
     source_root File.expand_path("templates", __dir__)
 
     desc "Install Hakumi Components in your Rails application"
 
+    sig { void }
     def add_npm_package
       say "Adding @hakumi-dev/hakumi-components to package.json...", :green
 
@@ -17,6 +21,7 @@ module HakumiComponents
       end
     end
 
+    sig { void }
     def setup_javascript
       say "Setting up JavaScript...", :green
 
@@ -80,6 +85,7 @@ module HakumiComponents
       end
     end
 
+    sig { void }
     def setup_stylesheets
       say "Setting up stylesheets...", :green
 
@@ -117,6 +123,7 @@ module HakumiComponents
       end
     end
 
+    sig { void }
     def setup_form_builder
       say "Setting up FormBuilder (optional)...", :green
 
@@ -136,6 +143,7 @@ module HakumiComponents
       end
     end
 
+    sig { void }
     def show_post_install
       say ""
       say "=" * 70, :green
@@ -170,6 +178,7 @@ module HakumiComponents
 
     private
 
+    sig { returns(T.nilable(String)) }
     def detect_js_entry_point
       # Check common JavaScript entry points in order of preference
       candidates = [
@@ -181,6 +190,7 @@ module HakumiComponents
       candidates.find { |file| File.exist?(file) }
     end
 
+    sig { returns(T.nilable(String)) }
     def detect_scss_file
       # Check common SCSS file locations
       candidates = [
@@ -192,6 +202,7 @@ module HakumiComponents
       candidates.find { |file| File.exist?(file) }
     end
 
+    sig { returns(T::Boolean) }
     def using_modern_bundler?
       # Detect if using Vite, Webpack, or esbuild (modern bundlers)
       File.exist?("vite.config.js") ||
@@ -202,12 +213,14 @@ module HakumiComponents
         (File.exist?("Gemfile") && File.read("Gemfile").include?("vite_rails"))
     end
 
+    sig { returns(Symbol) }
     def package_manager
       return :yarn if File.exist?("yarn.lock")
       return :npm if File.exist?("package-lock.json")
       :yarn # default
     end
 
+    sig { returns(T::Boolean) }
     def needs_manual_setup?
       !detect_js_entry_point || !detect_scss_file
     end

data/lib/hakumi_components/documentation/models.rb

@@ -0,0 +1,290 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Documentation
+    MemberHash = T.type_alias { T::Hash[String, T.nilable(T.any(String, T::Boolean))] }
+    SectionHash = T.type_alias { T::Hash[String, T.any(T.nilable(String), T::Array[MemberHash])] }
+    ExampleHash = T.type_alias { T::Hash[String, T.nilable(T.any(String, T::Boolean))] }
+    ComponentHash = T.type_alias do
+      T::Hash[String, T.any(
+        T.nilable(String),
+        T::Array[String],
+        T::Array[ExampleHash],
+        T::Array[SectionHash]
+      )]
+    end
+
+    class Member
+      extend T::Sig
+
+      sig do
+        params(
+          name: String,
+          description: T.nilable(String),
+          type: T.nilable(String),
+          default_value: T.nilable(String),
+          required: T.nilable(T::Boolean),
+          values: T.nilable(String),
+          example: T.nilable(String),
+          returns: T.nilable(String),
+          detail: T.nilable(String)
+        ).void
+      end
+      def initialize(
+        name:,
+        description: nil,
+        type: nil,
+        default_value: nil,
+        required: nil,
+        values: nil,
+        example: nil,
+        returns: nil,
+        detail: nil
+      )
+        @name = name
+        @description = description
+        @type = type
+        @default_value = default_value
+        @required = required
+        @values = values
+        @example = example
+        @returns = returns
+        @detail = detail
+      end
+
+      sig { returns(String) }
+      attr_reader :name
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :description
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :type
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :default_value
+
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :required
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :values
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :example
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :returns
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :detail
+
+      sig { returns(MemberHash) }
+      def to_h
+        {
+          "name" => @name,
+          "description" => @description,
+          "type" => @type,
+          "default" => @default_value,
+          "required" => @required,
+          "values" => @values,
+          "example" => @example,
+          "returns" => @returns,
+          "detail" => @detail
+        }
+      end
+    end
+
+    class Section
+      extend T::Sig
+
+      sig do
+        params(
+          title: String,
+          description: T.nilable(String),
+          props: T::Array[Member],
+          methods: T::Array[Member],
+          events: T::Array[Member],
+          slots: T::Array[Member]
+        ).void
+      end
+      def initialize(title:, description: nil, props: [], methods: [], events: [], slots: [])
+        @title = title
+        @description = description
+        @props = props
+        @methods = methods
+        @events = events
+        @slots = slots
+      end
+
+      sig { returns(String) }
+      attr_reader :title
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :description
+
+      sig { returns(T::Array[Member]) }
+      attr_reader :props
+
+      sig { returns(T::Array[Member]) }
+      attr_reader :methods
+
+      sig { returns(T::Array[Member]) }
+      attr_reader :events
+
+      sig { returns(T::Array[Member]) }
+      attr_reader :slots
+
+      sig { returns(SectionHash) }
+      def to_h
+        {
+          "title" => @title,
+          "description" => @description,
+          "props" => @props.map(&:to_h),
+          "methods" => @methods.map(&:to_h),
+          "events" => @events.map(&:to_h),
+          "slots" => @slots.map(&:to_h)
+        }
+      end
+    end
+
+    class Example
+      extend T::Sig
+
+      sig do
+        params(
+          name: String,
+          title: String,
+          description: T.nilable(String),
+          sandbox: T::Boolean,
+          content: T.nilable(String)
+        ).void
+      end
+      def initialize(name:, title:, description: nil, sandbox: false, content: nil)
+        @name = name
+        @title = title
+        @description = description
+        @sandbox = sandbox
+        @content = content
+      end
+
+      sig { returns(String) }
+      attr_reader :name
+
+      sig { returns(String) }
+      attr_reader :title
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :description
+
+      sig { returns(T::Boolean) }
+      attr_reader :sandbox
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :content
+
+      sig { params(content: T.nilable(String)).returns(Example) }
+      def with_content(content)
+        self.class.new(
+          name: @name,
+          title: @title,
+          description: @description,
+          sandbox: @sandbox,
+          content: content
+        )
+      end
+
+      sig { returns(ExampleHash) }
+      def to_h
+        {
+          "name" => @name,
+          "title" => @title,
+          "description" => @description,
+          "sandbox" => @sandbox,
+          "content" => @content
+        }
+      end
+    end
+
+    class Component
+      extend T::Sig
+
+      sig do
+        params(
+          name: String,
+          description: T.nilable(String),
+          category: T.nilable(String),
+          when_to_use: T::Array[String],
+          when_not_to_use: T::Array[String],
+          examples: T::Array[Example],
+          api_sections: T::Array[Section]
+        ).void
+      end
+      def initialize(
+        name:,
+        description: nil,
+        category: nil,
+        when_to_use: [],
+        when_not_to_use: [],
+        examples: [],
+        api_sections: []
+      )
+        @name = name
+        @description = description
+        @category = category
+        @when_to_use = when_to_use
+        @when_not_to_use = when_not_to_use
+        @examples = examples
+        @api_sections = api_sections
+      end
+
+      sig { returns(String) }
+      attr_reader :name
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :description
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :category
+
+      sig { returns(T::Array[String]) }
+      attr_reader :when_to_use
+
+      sig { returns(T::Array[String]) }
+      attr_reader :when_not_to_use
+
+      sig { returns(T::Array[Example]) }
+      attr_reader :examples
+
+      sig { returns(T::Array[Section]) }
+      attr_reader :api_sections
+
+      sig { params(examples: T::Array[Example]).returns(Component) }
+      def with_examples(examples)
+        self.class.new(
+          name: @name,
+          description: @description,
+          category: @category,
+          when_to_use: @when_to_use,
+          when_not_to_use: @when_not_to_use,
+          examples: examples,
+          api_sections: @api_sections
+        )
+      end
+
+      sig { returns(ComponentHash) }
+      def to_h
+        {
+          "name" => @name,
+          "description" => @description,
+          "category" => @category,
+          "when_to_use" => @when_to_use,
+          "when_not_to_use" => @when_not_to_use,
+          "examples" => @examples.map(&:to_h),
+          "api_sections" => @api_sections.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/hakumi_components/documentation/node.rb

@@ -0,0 +1,73 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Documentation
+    class Node
+      extend T::Sig
+
+      # T.untyped is intentional: wraps arbitrary parsed data (Hash, String, Array,
+      # Integer, Boolean, nil) from external sources like JSON config files.
+      sig { params(value: T.untyped).returns(Node) }
+      def self.wrap(value)
+        new(value)
+      end
+
+      sig { params(value: T.untyped).void }
+      def initialize(value)
+        @value = T.let(value, T.untyped)
+      end
+
+      sig { params(key: String).returns(Node) }
+      def fetch(key)
+        return self.class.wrap(nil) unless @value.is_a?(Hash)
+
+        value = @value[key]
+        self.class.wrap(value)
+      end
+
+      sig { returns(T.nilable(String)) }
+      def string
+        return @value if @value.is_a?(String)
+
+        nil
+      end
+
+      sig { returns(T.nilable(T::Boolean)) }
+      def boolean
+        return @value if @value == true || @value == false
+
+        nil
+      end
+
+      sig { returns(T.nilable(String)) }
+      def scalar_to_string
+        return nil if @value.nil?
+        return @value if @value.is_a?(String)
+        return @value.to_s if @value.is_a?(Symbol) || @value.is_a?(Numeric) || @value == true || @value == false
+
+        nil
+      end
+
+      sig { returns(T::Array[String]) }
+      def string_array
+        return [] unless @value.is_a?(Array)
+
+        @value.filter_map do |entry|
+          entry if entry.is_a?(String)
+        end
+      end
+
+      sig { returns(T::Array[Node]) }
+      def object_array
+        return [] unless @value.is_a?(Array)
+
+        @value.filter_map do |entry|
+          next unless entry.is_a?(Hash)
+
+          self.class.wrap(entry)
+        end
+      end
+    end
+  end
+end

data/lib/hakumi_components/documentation.rb

@@ -1,41 +1,28 @@
+# typed: strict
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "documentation/models"
+require_relative "documentation/node"
 
 module HakumiComponents
-  # Provides access to component documentation and examples.
-  # Documentation lives in app/components/hakumi/[component]/docs/ and includes:
-  # - meta.yml: Component metadata, API documentation, and example definitions
-  # - examples/*.erb: Example partials that demonstrate component usage
-  #
-  # NOTE: Documentation files are NOT included in the published gem.
-  # This module is primarily useful for:
-  # - Development playgrounds
-  # - Documentation generators
-  # - IDE tooling
-  #
-  # @example List all documented components
-  #   HakumiComponents::Documentation.components
-  #   # => ["button", "alert", "modal", ...]
-  #
-  # @example Get component metadata
-  #   HakumiComponents::Documentation.metadata("button")
-  #   # => { "name" => "Button", "description" => "...", "api" => [...] }
-  #
-  # @example Get example content
-  #   HakumiComponents::Documentation.example("button", "basic_types")
-  #   # => "<%= render(HakumiComponents::Button::Component.new..."
-  #
   module Documentation
+    INTERNAL_COMPONENTS = T.let(%w[
+      admin_panel
+      container
+      selection_control
+    ].freeze, T::Array[String])
+
     class << self
-      # Root path for component files
-      # @return [Pathname]
+      extend T::Sig
+
+      sig { returns(Pathname) }
       def components_root
+        @components_root = T.let(@components_root, T.nilable(Pathname)) unless instance_variable_defined?(:@components_root)
         @components_root ||= Pathname.new(File.expand_path("../../app/components/hakumi_components", __dir__.to_s))
       end
 
-      # List all components that have documentation
-      # @return [Array<String>] component names
+      sig { returns(T::Array[String]) }
       def components
         return [] unless components_root.exist?
 
@@ -45,30 +32,59 @@ module HakumiComponents
           .sort
       end
 
-      # Get metadata for a component
-      # @param component_name [String] the component name (e.g., "button")
-      # @return [Hash, nil] parsed meta.yml content or nil if not found
-      def metadata(component_name)
-        meta_path = meta_path_for(component_name)
-        return nil unless meta_path.exist?
+      sig { returns(T::Array[String]) }
+      def component_directories
+        return [] unless components_root.exist?
 
-        YAML.load_file(meta_path)
+        components_root.children
+          .select(&:directory?)
+          .map { |path| path.basename.to_s }
+          .reject { |name| name == "concerns" }
+          .sort
       end
 
-      # Get list of examples for a component
-      # @param component_name [String] the component name
-      # @return [Array<Hash>] example definitions from meta.yml
+      sig { returns(T::Array[String]) }
+      def internal_components
+        INTERNAL_COMPONENTS
+      end
+
+      sig { returns(T::Array[String]) }
+      def public_components
+        components - internal_components
+      end
+
+      sig { params(component_name: String).returns(T::Boolean) }
+      def internal_component?(component_name)
+        internal_components.include?(component_name)
+      end
+
+      sig { params(component_name: String).returns(T.nilable(Component)) }
+      def metadata(component_name)
+        meta = raw_metadata(component_name)
+        return nil unless meta
+
+        Component.new(
+          name: meta.fetch("name").string || component_name.tr("_", " ").split.map(&:capitalize).join(" "),
+          description: meta.fetch("description").string,
+          category: meta.fetch("category").string,
+          when_to_use: meta.fetch("when_to_use").string_array,
+          when_not_to_use: meta.fetch("when_not_to_use").string_array,
+          examples: build_examples(meta),
+          api_sections: build_sections(meta)
+        )
+      end
+
+      sig { params(component_name: String).returns(T::Array[Example]) }
       def examples(component_name)
         meta = metadata(component_name)
         return [] unless meta
 
-        meta["examples"] || []
+        meta.examples.map do |doc_example|
+          doc_example.with_content(example(component_name, doc_example.name))
+        end
       end
 
-      # Get the content of an example partial
-      # @param component_name [String] the component name
-      # @param example_name [String] the example name (without underscore or extension)
-      # @return [String, nil] the example ERB content or nil if not found
+      sig { params(component_name: String, example_name: String).returns(T.nilable(String)) }
       def example(component_name, example_name)
         example_path = example_path_for(component_name, example_name)
         return nil unless example_path
@@ -76,52 +92,113 @@ module HakumiComponents
         example_path.read
       end
 
-      # Get the path to an example partial (for rendering in Rails)
-      # @param component_name [String] the component name
-      # @param example_name [String] the example name
-      # @return [Pathname, nil] the path to the example file or nil if not found
+      sig { params(component_name: String, example_name: String).returns(T.nilable(Pathname)) }
       def example_path_for(component_name, example_name)
         path = components_root / component_name / "docs" / "examples" / "_#{example_name}.html.erb"
         path.exist? ? path : nil
       end
 
-      # Get the API documentation for a component
-      # @param component_name [String] the component name
-      # @return [Array<Hash>] API property definitions
+      sig { params(component_name: String).returns(T::Array[Section]) }
       def api(component_name)
         meta = metadata(component_name)
         return [] unless meta
 
-        meta["api"] || []
+        meta.api_sections
       end
 
-      # Get all documentation as a hash (useful for JSON export)
-      # @return [Hash] all component documentation
+      sig { returns(T::Hash[String, Component]) }
       def all
-        result = Hash.new
+        result = T.let({}, T::Hash[String, Component])
         components.each do |name|
-          result[name] = {
-            metadata: metadata(name),
-            examples: examples(name).map do |ex|
-              ex.merge("content" => example(name, ex["name"]))
-            end
-          }
+          documentation = metadata(name)
+          next unless documentation
+
+          result[name] = documentation.with_examples(examples(name))
         end
         result
       end
 
-      # Export all documentation to JSON
-      # @return [String] JSON representation
+      sig { params(_args: String).returns(String) }
       def to_json(*_args)
         require "json"
-        JSON.pretty_generate(all)
+
+        serialized = T.let({}, T::Hash[String, ComponentHash])
+        all.each do |name, documentation|
+          serialized[name] = documentation.to_h
+        end
+
+        JSON.pretty_generate(serialized)
       end
 
       private
 
+      sig { params(component_name: String).returns(T.nilable(Node)) }
+      def raw_metadata(component_name)
+        meta_path = meta_path_for(component_name)
+        return nil unless meta_path.exist?
+
+        raw = YAML.load_file(meta_path)
+        return nil unless raw.is_a?(Hash)
+
+        Node.wrap(raw)
+      end
+
+      sig { params(component_name: String).returns(Pathname) }
       def meta_path_for(component_name)
         components_root / component_name / "docs" / "meta.yml"
       end
+
+      sig { params(meta: Node).returns(T::Array[Example]) }
+      def build_examples(meta)
+        meta.fetch("examples").object_array.filter_map do |example|
+          name = example.fetch("name").string
+          next unless name
+
+          Example.new(
+            name: name,
+            title: example.fetch("title").string || name.tr("_", " ").split.map(&:capitalize).join(" "),
+            description: example.fetch("description").string,
+            sandbox: example.fetch("sandbox").boolean || false
+          )
+        end
+      end
+
+      sig { params(meta: Node).returns(T::Array[Section]) }
+      def build_sections(meta)
+        meta.fetch("api_sections").object_array.filter_map do |section|
+          title = section.fetch("title").string
+          next unless title
+
+          Section.new(
+            title: title,
+            description: section.fetch("description").string,
+            props: build_members(section, "props"),
+            methods: build_members(section, "methods"),
+            events: build_members(section, "events"),
+            slots: build_members(section, "slots")
+          )
+        end
+      end
+
+      sig { params(section: Node, key: String).returns(T::Array[Member]) }
+      def build_members(section, key)
+        section.fetch(key).object_array.filter_map do |member|
+          name = member.fetch("name").string
+          next unless name
+
+          Member.new(
+            name: name,
+            description: member.fetch("description").string,
+            type: member.fetch("type").string,
+            default_value: member.fetch("default").scalar_to_string,
+            required: member.fetch("required").boolean,
+            values: member.fetch("values").scalar_to_string,
+            example: member.fetch("example").string,
+            returns: member.fetch("returns").string,
+            detail: member.fetch("detail").string
+          )
+        end
+      end
     end
   end
 end