nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/component.rb

@@ -2,72 +2,314 @@
 
 module NitroKit
   class Component < Phlex::HTML
-    def initialize(attrs = {}, **defaults)
-      @attrs = merge_attrs(attrs, **defaults)
+    DeferredContent = Data.define(:text, :block)
+    private_constant :DeferredContent
+    # Data keys a component sets for itself through `attributes:`.
+    COMPONENT_OWNED_DATA_ATTRIBUTES = %w[
+      state disabled required orientation presentation placement layout side field-type
+    ].freeze
+    # Every data key Nitro owns. Applications may not pass any of them through `data:`.
+    RESERVED_DATA_ATTRIBUTES = (
+      %w[nk slot variant size nk-escape enhanced] + COMPONENT_OWNED_DATA_ATTRIBUTES
+    ).freeze
+    ADDITIVE_DATA_ATTRIBUTES = %w[action controller].freeze
+    FORBIDDEN_ATTRIBUTES = %w[class style].freeze
+
+    def initialize(
+      component:,
+      attributes: {},
+      html: {},
+      aria: {},
+      data: {},
+      variant: nil,
+      size: nil,
+      desperately_need_a_class: nil
+    )
+      @component_name = normalize_identity(component, name: "component")
+      @attrs = owned_attributes(
+        attributes:,
+        html:,
+        aria:,
+        data:,
+        owned_data: {
+          nk: @component_name,
+          variant: variant && normalize_identity(variant, name: "variant"),
+          size: size && normalize_identity(size, name: "size")
+        }.compact,
+        desperately_need_a_class:
+      )
     end
 
-    attr_reader :attrs
+    private
 
-    def self.from_template(*args, **attrs, &block)
-      new(*args, **attrs, &block).tap { |instance| instance.instance_variable_set(:@_nk_from_template, true) }
+    def root_attributes
+      @attrs
     end
 
-    def builder(&block)
-      @_nk_from_template && !self.is_a?(NitroKit::Component) ? capture(&block) : yield
+    def slot_attributes(
+      slot,
+      attributes: {},
+      html: {},
+      aria: {},
+      data: {},
+      variant: nil,
+      desperately_need_a_class: nil
+    )
+      raise ArgumentError, "Slots require a component identity" unless @component_name
+
+      owned_attributes(
+        attributes:,
+        html:,
+        aria:,
+        data:,
+        owned_data: {
+          slot: qualified_slot(slot),
+          variant: variant && normalize_identity(variant, name: "variant")
+        }.compact,
+        desperately_need_a_class:
+      )
     end
 
-    private
+    def render_in_slot(component, slot, &block)
+      unless component.is_a?(NitroKit::Component)
+        raise ArgumentError, "Slots can only contain NitroKit::Component instances"
+      end
 
-    # Class-level helper method for builder style components.
-    # When called from erb or templates, we need to wrap the return value
-    # in capture so we don't write to the output buffer immediately.
-    # However when called from other components, we don't.
-    def self.builder_method(method_name)
-      warn(
-        "[DEPRECATION] builder_method is deprecated. Please migrate to using the builder(&) pattern. See https://github.com/mikker/nitro_kit/issues/35 for details."
-      )
+      component.__send__(:attach_to_slot!, qualified_slot(slot))
+      render(component, &block)
+    end
+
+    def validate_choice!(name, value, choices)
+      return value if choices.include?(value)
 
-      nil
+      raise ArgumentError, "Unknown #{name} #{value.inspect}; expected one of: #{choices.map(&:inspect).join(", ")}"
     end
 
-    # Merge attributes with some special cases for matching keys
-    def merge_attrs(*hashes, **defaults)
-      defaults
-        .merge(*hashes) do |key, old_value, new_value|
-          case key
-          when :class
-            # Use TailwindMerge to merge class names
-            merge_class(old_value, new_value)
-          when :data
-            # Merge data hashes with some special cases for Stimulus
-            merge_data(old_value, new_value)
-          else
-            new_value
-          end
+    def validate_boolean!(name, value, allow_nil: false)
+      return value if value == true || value == false
+      return value if allow_nil && value.nil?
+
+      expected = allow_nil ? "true, false, or nil" : "true or false"
+      raise ArgumentError, "#{name} must be #{expected}; received #{value.inspect}"
+    end
+
+    def owned_attributes(attributes:, html:, aria:, data:, owned_data:, desperately_need_a_class:)
+      attributes = attribute_hash(attributes, name: "attributes")
+      html = attribute_hash(html, name: "html")
+      aria = attribute_hash(aria, name: "aria")
+      data = attribute_hash(data, name: "data")
+
+      internal_aria = extract_nested_attributes!(attributes, :aria)
+      internal_data = extract_nested_attributes!(attributes, :data)
+      internal_aria = normalize_aria_values(internal_aria)
+      aria = normalize_aria_values(aria)
+
+      validate_html_attributes!(attributes, source: "attributes")
+      validate_html_attributes!(html, source: "html")
+      validate_public_data!(data)
+      validate_internal_data!(internal_data)
+
+      merged = merge_distinct_attributes(attributes, html)
+      merged_aria = merge_distinct_attributes(internal_aria, aria, name: "ARIA")
+      merged_data = merge_owned_data(owned_data, internal_data, data)
+
+      merged[:aria] = merged_aria if merged_aria.any?
+      merged[:data] = merged_data if merged_data.any?
+
+      unless desperately_need_a_class.nil?
+        validate_class_escape!(desperately_need_a_class)
+        merged[:class] = desperately_need_a_class
+        merged[:data] = merge_owned_data(merged.fetch(:data, {}), { nk_escape: "class" })
+      end
+
+      merged
+    end
+
+    def attribute_hash(value, name:)
+      return value.dup if value.is_a?(Hash)
+
+      raise ArgumentError, "#{name} must be a Hash"
+    end
+
+    def extract_nested_attributes!(attributes, name)
+      key = attributes.keys.find { |candidate| normalized_attribute(candidate) == name.to_s }
+      return {} unless key
+
+      attribute_hash(attributes.delete(key), name:)
+    end
+
+    def validate_html_attributes!(attributes, source:)
+      attributes.each_key do |key|
+        normalized = normalized_attribute(key)
+
+        if FORBIDDEN_ATTRIBUTES.include?(normalized)
+          raise ArgumentError, "#{normalized}: is not allowed; use desperately_need_a_class: for classes"
+        end
+
+        if normalized == "data" || normalized == "aria" || normalized.start_with?("data-") || normalized.start_with?("aria-")
+          boundary = normalized.start_with?("aria") ? "aria" : "data"
+          raise ArgumentError, "Pass #{normalized} through #{boundary}:, not #{source}:"
         end
+      end
     end
 
-    alias :mattr :merge_attrs
+    def validate_public_data!(data)
+      data.each_key do |key|
+        normalized = normalized_data_attribute(key)
+        next unless RESERVED_DATA_ATTRIBUTES.include?(normalized)
 
-    def merge_class(*args)
-      @@merger ||= TailwindMerge::Merger.new
-      @@merger.merge(args)
+        raise ArgumentError, "data-#{normalized} is reserved by Nitro Kit"
+      end
     end
 
-    def merge_data(*hashes)
-      hashes
-        .compact
-        .reduce({}) do |acc, hash|
-          acc.deep_merge(hash) do |key, old_val, new_val|
-            # Concat Stimulus actions
-            case key
-            when :action, :controller
-              [ new_val, old_val ].compact.join(" ")
-            else
-              new_val
+    def validate_internal_data!(data)
+      base_owned = RESERVED_DATA_ATTRIBUTES - COMPONENT_OWNED_DATA_ATTRIBUTES
+
+      data.each_key do |key|
+        normalized = normalized_data_attribute(key)
+        next unless base_owned.include?(normalized)
+
+        raise ArgumentError, "Use the component or slot API for data-#{normalized}"
+      end
+    end
+
+    def merge_distinct_attributes(*hashes, name: "HTML")
+      hashes.compact.reduce({}) do |merged, attributes|
+        attributes.each do |key, value|
+          existing_key = merged.keys.find do |candidate|
+            normalized_attribute(candidate) == normalized_attribute(key)
+          end
+
+          if existing_key
+            raise ArgumentError, "Duplicate #{name} attribute #{normalized_attribute(key)}"
+          end
+
+          merged[key] = value
+        end
+
+        merged
+      end
+    end
+
+    def merge_owned_data(*hashes)
+      hashes.compact.reduce({}) do |merged, attributes|
+        attributes.each do |key, value|
+          existing_key = merged.keys.find do |candidate|
+            normalized_data_attribute(candidate) == normalized_data_attribute(key)
+          end
+
+          if existing_key
+            normalized = normalized_data_attribute(key)
+
+            unless ADDITIVE_DATA_ATTRIBUTES.include?(normalized)
+              raise ArgumentError, "Duplicate data-#{normalized} attribute"
             end
+
+            merged[existing_key] = [ merged[existing_key], value ].flatten.compact.join(" ")
+          else
+            merged[key] = value
           end
         end
+
+        merged
+      end
+    end
+
+    def normalize_identity(value, name:)
+      normalized = value.to_s.strip.tr("_", "-")
+      raise ArgumentError, "#{name} cannot be blank" if normalized.empty?
+      unless normalized.match?(/\A[a-z0-9-]+\z/)
+        raise ArgumentError, "#{name} must contain only lowercase letters, numbers, and hyphens"
+      end
+
+      normalized
+    end
+
+    def qualified_slot(slot)
+      raise ArgumentError, "Slots require a component identity" unless @component_name
+
+      slot_name = normalize_identity(slot, name: "slot")
+      slot_name.start_with?("#{@component_name}-") ? slot_name : "#{@component_name}-#{slot_name}"
+    end
+
+    def attach_to_slot!(slot)
+      raise ArgumentError, "Nested slots require a component identity" unless @component_name
+
+      data = @attrs.fetch(:data, {})
+      if data.keys.any? { |key| normalized_data_attribute(key) == "slot" }
+        raise ArgumentError, "Component is already attached to a slot"
+      end
+
+      @attrs = @attrs.merge(data: merge_owned_data(data, { slot: }))
+    end
+
+    def normalized_attribute(key)
+      key.to_s.downcase.tr("_", "-")
+    end
+
+    def normalized_data_attribute(key)
+      normalized_attribute(key).delete_prefix("data-")
+    end
+
+    def normalized_aria_attribute(key)
+      normalized_attribute(key).delete_prefix("aria-")
+    end
+
+    # Conventions shared by the labelled control components. They read the
+    # `@label`, `@description`, `@id`, `@control_aria`, and `@invalid` state
+    # those components already keep.
+
+    def description_id
+      "#{@id}-description" if @id && @description
+    end
+
+    def control_aria
+      attributes = @control_aria.dup
+      key = attributes.keys.find { |candidate| normalized_aria_attribute(candidate) == "describedby" }
+      attributes[:describedby] = [ attributes.delete(key), description_id ].compact.join(" ").presence
+      attributes[:invalid] = "true" if @invalid
+      attributes
+    end
+
+    def require_accessible_name!(&block)
+      labelled = !@label.nil? || !block.nil?
+
+      unless labelled || accessible_name?
+        raise ArgumentError, "#{component_words} requires a label, block, or accessible control name"
+      end
+
+      if @description && !labelled
+        raise ArgumentError, "#{component_words} description requires label text or block content"
+      end
+    end
+
+    def accessible_name?
+      @control_aria.any? do |key, value|
+        %w[label labelledby].include?(normalized_aria_attribute(key)) && value.to_s.present?
+      end
+    end
+
+    def component_words
+      @component_name.tr("-", " ")
+    end
+
+    def validate_optional_text!(name, text)
+      return if text.nil?
+      return text if text.is_a?(String) && !text.strip.empty?
+
+      raise ArgumentError, "#{name} must be a non-blank String or nil"
+    end
+
+    def normalize_aria_values(attributes)
+      attributes.transform_values do |value|
+        value == true || value == false ? value.to_s : value
+      end
+    end
+
+    def validate_class_escape!(value)
+      return if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, "desperately_need_a_class: must be a non-blank String"
     end
 
     def text_or_block(text = nil, &block)
@@ -81,5 +323,39 @@ module NitroKit
         nil
       end
     end
+
+    def content_from_keyword(name, text)
+      return if text.nil?
+
+      validate_content_text!(name, text)
+      DeferredContent.new(text:, block: nil)
+    end
+
+    def declare_content(name, current, text = nil, &block)
+      raise ArgumentError, "#{name} has already been provided" if current
+      raise ArgumentError, "#{name} accepts text or a block, not both" if !text.nil? && block
+
+      unless block
+        validate_content_text!(name, text)
+      end
+
+      DeferredContent.new(text:, block:)
+    end
+
+    def require_content!(component, name, content)
+      return content if content
+
+      raise ArgumentError, "#{component} requires #{name} through the constructor or compound method"
+    end
+
+    def render_deferred_content(content)
+      text_or_block(content.text, &content.block)
+    end
+
+    def validate_content_text!(name, text)
+      return text if text.is_a?(String) && !text.strip.empty?
+
+      raise ArgumentError, "#{name} must be a non-blank String or a block"
+    end
   end
 end

data/app/components/nitro_kit/container.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class Container < Component
+    SIZES = %i[sm md lg xl].freeze
+
+    def initialize(
+      size:,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      size = validate_choice!(:size, size, SIZES)
+
+      super(
+        component: :container,
+        attributes: { id: }.compact,
+        html:,
+        aria:,
+        data:,
+        size:,
+        desperately_need_a_class:
+      )
+    end
+
+    def view_template
+      div(**root_attributes) { yield if block_given? }
+    end
+  end
+end

data/app/components/nitro_kit/control_group.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class ControlGroup < Component
+    def initialize(label: nil, id: nil, html: {}, aria: {}, data: {}, desperately_need_a_class: nil)
+      unless label.nil? || (label.is_a?(String) && label.present?)
+        raise ArgumentError, "ControlGroup label: must be nil or a non-blank String"
+      end
+
+      super(
+        component: :control_group,
+        attributes: {
+          id:,
+          role: label ? "group" : nil,
+          aria: { label: }.compact
+        },
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    def view_template
+      raise ArgumentError, "ControlGroup requires a block" unless block_given?
+
+      @rendering = true
+      div(**root_attributes) { yield(self) }
+    ensure
+      @rendering = false
+    end
+
+    def addon(text = nil, html: {}, aria: {}, data: {}, desperately_need_a_class: nil, &block)
+      raise ArgumentError, "ControlGroup addon must be declared inside the render block" unless @rendering
+      raise ArgumentError, "ControlGroup addon accepts text or a block, not both" if text && block
+      unless block || (text.is_a?(String) && text.present?)
+        raise ArgumentError, "ControlGroup addon requires non-blank text or a block"
+      end
+
+      span(**slot_attributes(:addon, html:, aria:, data:, desperately_need_a_class:)) do
+        text_or_block(text, &block)
+      end
+    end
+  end
+end

data/app/components/nitro_kit/danger_zone.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class DangerZone < Component
+    Child = Data.define(:component, :content)
+
+    def initialize(
+      title: nil,
+      description: nil,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @title_content = content_from_keyword(:title, title)
+      @description_content = content_from_keyword(:description, description)
+      @confirmation = nil
+      @escape = nil
+
+      super(
+        component: :danger_zone,
+        attributes: { id: }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    def view_template
+      yield self if block_given?
+      require_content!("DangerZone", :title, @title_content)
+      require_content!("DangerZone", :description, @description_content)
+      raise ArgumentError, "DangerZone requires exactly one confirmation" unless @confirmation
+
+      section(**root_attributes) do
+        header(**slot_attributes(:header)) do
+          h2(**slot_attributes(:title)) { render_deferred_content(@title_content) }
+          p(**slot_attributes(:description)) { render_deferred_content(@description_content) }
+        end
+        div(**slot_attributes(:confirmation), &@confirmation)
+        render_in_slot(@escape.component, :escape, &@escape.content) if @escape
+      end
+    end
+
+    def title(text = nil, &block)
+      @title_content = declare_content(:title, @title_content, text, &block)
+      nil
+    end
+
+    def description(text = nil, &block)
+      @description_content = declare_content(:description, @description_content, text, &block)
+      nil
+    end
+
+    def confirmation(&content)
+      raise ArgumentError, "DangerZone confirmation requires a block" unless content
+      raise ArgumentError, "DangerZone accepts exactly one confirmation" if @confirmation
+
+      @confirmation = content
+      nil
+    end
+
+    def escape(component, &content)
+      unless component.is_a?(NitroKit::Button)
+        raise ArgumentError, "DangerZone escape must be a NitroKit::Button"
+      end
+      if component.variant == :destructive
+        raise ArgumentError, "DangerZone escape cannot use the destructive Button variant"
+      end
+      raise ArgumentError, "DangerZone accepts at most one safe escape action" if @escape
+
+      @escape = Child.new(component:, content:)
+      nil
+    end
+  end
+end

data/app/components/nitro_kit/data_section.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class DataSection < Component
+    Child = Data.define(:component, :content)
+
+    def initialize(
+      title: nil,
+      description: nil,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @title_content = content_from_keyword(:title, title)
+      @description_content = content_from_keyword(:description, description)
+      @actions = nil
+      @content = nil
+
+      super(
+        component: :data_section,
+        attributes: { id: }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    def view_template
+      yield self if block_given?
+      require_content!("DataSection", :title, @title_content)
+      raise ArgumentError, "DataSection requires exactly one table or EmptyState" unless @content
+
+      section(**root_attributes) do
+        header(**slot_attributes(:header)) do
+          div(**slot_attributes(:heading)) do
+            h2(**slot_attributes(:title)) { render_deferred_content(@title_content) }
+            if @description_content
+              p(**slot_attributes(:description)) { render_deferred_content(@description_content) }
+            end
+          end
+          render_in_slot(@actions.component, :actions, &@actions.content) if @actions
+        end
+        render_in_slot(@content.component, content_slot, &@content.content)
+      end
+    end
+
+    def title(text = nil, &block)
+      @title_content = declare_content(:title, @title_content, text, &block)
+      nil
+    end
+
+    def description(text = nil, &block)
+      @description_content = declare_content(:description, @description_content, text, &block)
+      nil
+    end
+
+    alias :html_table :table
+
+    def actions(component, &content)
+      unless component.is_a?(NitroKit::ButtonGroup) || component.is_a?(NitroKit::Button)
+        raise ArgumentError, "DataSection actions must be a NitroKit::ButtonGroup or NitroKit::Button"
+      end
+      raise ArgumentError, "DataSection accepts at most one actions group" if @actions
+
+      @actions = Child.new(component:, content:)
+      nil
+    end
+
+    def table(component, &content)
+      unless table_component?(component)
+        raise ArgumentError, "DataSection table must be a NitroKit::Table or NitroKit::DetailsTable"
+      end
+
+      assign_content(component, &content)
+    end
+
+    def empty_state(component, &content)
+      unless component.is_a?(NitroKit::EmptyState)
+        raise ArgumentError, "DataSection empty_state must be a NitroKit::EmptyState"
+      end
+      raise ArgumentError, "DataSection EmptyState must use level: 3" if component.level != 3
+
+      assign_content(component, &content)
+    end
+
+    private
+
+    def table_component?(component)
+      component.is_a?(NitroKit::Table) || component.is_a?(NitroKit::DetailsTable)
+    end
+
+    def assign_content(component, &content)
+      raise ArgumentError, "DataSection accepts exactly one table or EmptyState" if @content
+
+      @content = Child.new(component:, content:)
+      nil
+    end
+
+    def content_slot
+      table_component?(@content.component) ? :table : :empty_state
+    end
+  end
+end