nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.4

data/app/components/nitro_kit/component.rb

@@ -7,6 +7,7 @@ module NitroKit
     # Data keys a component sets for itself through `attributes:`.
     COMPONENT_OWNED_DATA_ATTRIBUTES = %w[
       state disabled required orientation presentation placement layout side field-type
+      dir gap align justify wrap cols mode key
     ].freeze
     # Every data key Nitro owns. Applications may not pass any of them through `data:`.
     RESERVED_DATA_ATTRIBUTES = (
@@ -93,6 +94,18 @@ module NitroKit
       raise ArgumentError, "#{name} must be #{expected}; received #{value.inspect}"
     end
 
+    def validate_id!(name, value)
+      return value if value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+
+      raise ArgumentError, "#{name} must be a fragment-safe String using letters, numbers, underscores, or hyphens"
+    end
+
+    def validate_text!(name, text)
+      return text if text.is_a?(String) && !text.strip.empty?
+
+      raise ArgumentError, "#{name} must be a non-blank String"
+    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")
@@ -117,8 +130,7 @@ module NitroKit
       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[:class] = normalize_class_escape(desperately_need_a_class)
         merged[:data] = merge_owned_data(merged.fetch(:data, {}), { nk_escape: "class" })
       end
 
@@ -293,6 +305,43 @@ module NitroKit
       @component_name.tr("-", " ")
     end
 
+    # Conventions shared by the choice group components. They read the `id`
+    # and `options` readers those components already keep.
+
+    def deterministic_id(name)
+      derived = name.to_s.gsub(/[^a-zA-Z0-9_-]+/, "_").gsub(/\A_+|_+\z/, "")
+      return derived unless derived.empty?
+
+      raise ArgumentError, "name #{name.inspect} cannot derive an id; pass id:"
+    end
+
+    def choice_id(index)
+      "#{id}-#{index}" if id
+    end
+
+    def validate_unique_choices!
+      duplicate_value = options.group_by { |choice| choice.value.to_s }.find { |_value, matches| matches.many? }
+      raise ArgumentError, "choice values must be unique" if duplicate_value
+
+      ids = options.each_with_index.filter_map { |choice, index| choice.id || choice_id(index) }
+      raise ArgumentError, "choice ids must be unique" unless ids.uniq.length == ids.length
+    end
+
+    # Command invoker plumbing shared by the nk--dialog overlay components.
+
+    def command_attributes(html, command, commandfor:, disabled: false)
+      raise ArgumentError, "html must be a Hash" unless html.is_a?(Hash)
+
+      collision = html.keys.find { |key| %w[command commandfor].include?(key.to_s.downcase) }
+      raise ArgumentError, "#{collision}: is owned by #{component_words.capitalize}" if collision
+
+      disabled ? html : html.merge(command:, commandfor:)
+    end
+
+    def command_data(data, command, disabled: false)
+      disabled ? data : data.merge(nk__dialog_command: command)
+    end
+
     def validate_optional_text!(name, text)
       return if text.nil?
       return text if text.is_a?(String) && !text.strip.empty?
@@ -306,10 +355,13 @@ module NitroKit
       end
     end
 
-    def validate_class_escape!(value)
-      return if value.is_a?(String) && !value.strip.empty?
+    def normalize_class_escape(value)
+      tokens = ActionView::Helpers::TagHelper.build_tag_values(value)
+        .flat_map { CGI.unescape_html(_1.to_s).split }
+        .uniq
+      return tokens.join(" ") if tokens.any?
 
-      raise ArgumentError, "desperately_need_a_class: must be a non-blank String"
+      raise ArgumentError, "desperately_need_a_class: must contain at least one class name"
     end
 
     def text_or_block(text = nil, &block)

data/app/components/nitro_kit/danger_zone.rb

@@ -2,11 +2,14 @@
 
 module NitroKit
   class DangerZone < Component
+    TITLE_LEVELS = (1..6).freeze
+
     Child = Data.define(:component, :content)
 
     def initialize(
       title: nil,
       description: nil,
+      level: 2,
       id: nil,
       html: {},
       aria: {},
@@ -15,6 +18,7 @@ module NitroKit
     )
       @title_content = content_from_keyword(:title, title)
       @description_content = content_from_keyword(:description, description)
+      @level = validate_choice!(:level, level, TITLE_LEVELS)
       @confirmation = nil
       @escape = nil
 
@@ -36,7 +40,7 @@ module NitroKit
 
       section(**root_attributes) do
         header(**slot_attributes(:header)) do
-          h2(**slot_attributes(:title)) { render_deferred_content(@title_content) }
+          public_send(:"h#{@level}", **slot_attributes(:title)) { render_deferred_content(@title_content) }
           p(**slot_attributes(:description)) { render_deferred_content(@description_content) }
         end
         div(**slot_attributes(:confirmation), &@confirmation)

data/app/components/nitro_kit/data_section.rb

@@ -2,11 +2,13 @@
 
 module NitroKit
   class DataSection < Component
+    TITLE_LEVELS = (1..6).freeze
     Child = Data.define(:component, :content)
 
     def initialize(
       title: nil,
       description: nil,
+      level: 2,
       id: nil,
       html: {},
       aria: {},
@@ -15,12 +17,14 @@ module NitroKit
     )
       @title_content = content_from_keyword(:title, title)
       @description_content = content_from_keyword(:description, description)
+      @level = validate_choice!(:level, level, TITLE_LEVELS)
       @actions = nil
       @content = nil
+      @title_id = "#{id || "nk-data-section-#{SecureRandom.hex(4)}"}-title"
 
       super(
         component: :data_section,
-        attributes: { id: }.compact,
+        attributes: { id:, aria: { labelledby: @title_id } }.compact,
         html:,
         aria:,
         data:,
@@ -28,15 +32,17 @@ module NitroKit
       )
     end
 
-    def view_template
-      yield self if block_given?
+    def view_template(&block)
+      collect_declarations(&block)
       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) }
+            public_send(:"h#{@level}", **slot_attributes(:title, attributes: { id: @title_id })) do
+              render_deferred_content(@title_content)
+            end
             if @description_content
               p(**slot_attributes(:description)) { render_deferred_content(@description_content) }
             end
@@ -48,6 +54,7 @@ module NitroKit
     end
 
     def title(text = nil, &block)
+      ensure_collecting!
       @title_content = declare_content(:title, @title_content, text, &block)
       nil
     end
@@ -60,6 +67,7 @@ module NitroKit
     alias :html_table :table
 
     def actions(component, &content)
+      ensure_collecting!
       unless component.is_a?(NitroKit::ButtonGroup) || component.is_a?(NitroKit::Button)
         raise ArgumentError, "DataSection actions must be a NitroKit::ButtonGroup or NitroKit::Button"
       end
@@ -70,6 +78,7 @@ module NitroKit
     end
 
     def table(component, &content)
+      ensure_collecting!
       unless table_component?(component)
         raise ArgumentError, "DataSection table must be a NitroKit::Table or NitroKit::DetailsTable"
       end
@@ -88,6 +97,21 @@ module NitroKit
 
     private
 
+    def collect_declarations
+      return unless block_given?
+
+      @collecting = true
+      yield(self)
+    ensure
+      @collecting = false
+    end
+
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "DataSection content must be declared inside the render block"
+    end
+
     def table_component?(component)
       component.is_a?(NitroKit::Table) || component.is_a?(NitroKit::DetailsTable)
     end

data/app/components/nitro_kit/details_table.rb

@@ -43,8 +43,8 @@ module NitroKit
 
     attr_reader :record, :route_base
 
-    def view_template
-      yield self if block_given?
+    def view_template(&block)
+      collect_declarations(&block)
       raise ArgumentError, "DetailsTable requires at least one field" if @fields.empty?
 
       div(**root_attributes) do
@@ -65,6 +65,7 @@ module NitroKit
     end
 
     def field(attribute, label: nil, value: UNSET, &content)
+      ensure_collecting!
       attribute = validate_attribute!(attribute)
       if @fields.any? { |field| field.attribute.to_s == attribute.to_s }
         raise ArgumentError, "DetailsTable field keys must be unique: #{attribute.inspect}"
@@ -78,6 +79,21 @@ module NitroKit
 
     private
 
+    def collect_declarations
+      return unless block_given?
+
+      @collecting = true
+      yield(self)
+    ensure
+      @collecting = false
+    end
+
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "DetailsTable fields must be declared inside the render block"
+    end
+
     def render_field(field)
       @table.tr do
         @table.th(field.label, scope: :row)
@@ -114,12 +130,7 @@ module NitroKit
 
     def render_string(value)
       if value.start_with?("https://", "http://")
-        a(
-          **slot_attributes(
-            :link,
-            attributes: { href: value, target: "_blank", rel: "noopener noreferrer" }
-          )
-        ) { plain(value) }
+        a(**slot_attributes(:link, attributes: { href: value })) { plain(value) }
       else
         plain(value)
       end

data/app/components/nitro_kit/dialog.rb

@@ -2,7 +2,7 @@
 
 module NitroKit
   class Dialog < Component
-    Trigger = ::Data.define(:text, :variant, :size, :disabled, :html, :aria, :data, :css_class, :content)
+    Trigger = ::Data.define(:text, :variant, :size, :icon, :icon_end, :label, :disabled, :html, :aria, :data, :css_class, :content)
     private_constant :Trigger
 
     Panel = ::Data.define(:title, :description, :nonmodal, :html, :aria, :data, :css_class, :content)
@@ -32,6 +32,10 @@ module NitroKit
           id:,
           data: {
             controller: "nk--dialog",
+            action: [
+              "click->nk--dialog#invoke",
+              "turbo:before-cache@document->nk--dialog#closeForCache"
+            ].join(" "),
             nk__dialog_dismissible_value: @dismissible
           }
         },
@@ -57,6 +61,9 @@ module NitroKit
       text = nil,
       variant: :default,
       size: :md,
+      icon: nil,
+      icon_end: nil,
+      label: nil,
       disabled: false,
       html: {},
       aria: {},
@@ -71,6 +78,9 @@ module NitroKit
         text:,
         variant:,
         size:,
+        icon:,
+        icon_end:,
+        label:,
         disabled: validate_boolean!(:disabled, disabled),
         html:,
         aria:,
@@ -115,7 +125,7 @@ module NitroKit
     end
 
     def close_button(
-      label: I18n.t("nitro_kit.dialog.close"),
+      label: default_close_label,
       html: {},
       aria: {},
       data: {},
@@ -159,10 +169,13 @@ module NitroKit
         @trigger.text,
         variant: @trigger.variant,
         size: @trigger.size,
+        icon: @trigger.icon,
+        icon_end: @trigger.icon_end,
+        label: @trigger.label,
         disabled: @trigger.disabled,
-        html: with_command(@trigger.html, "show-modal", disabled: @trigger.disabled),
+        html: command_attributes(@trigger.html, "show-modal", commandfor: element_id(:panel), disabled: @trigger.disabled),
         aria: @trigger.aria.merge(haspopup: "dialog"),
-        data: @trigger.data,
+        data: command_data(@trigger.data, "show-modal", disabled: @trigger.disabled),
         desperately_need_a_class: @trigger.css_class
       )
 
@@ -191,7 +204,7 @@ module NitroKit
             aria: owned_aria,
             data: {
               nk__dialog_target: "panel",
-              action: "click->nk--dialog#dismiss cancel->nk--dialog#cancel"
+              action: "click->nk--dialog#dismiss cancel->nk--dialog#cancel close->nk--dialog#restoreFocus"
             }
           },
           html: @panel.html,
@@ -221,7 +234,7 @@ module NitroKit
 
     def render_close_button
       declaration = @close_button || CloseButton.new(
-        label: I18n.t("nitro_kit.dialog.close"),
+        label: default_close_label,
         html: {},
         aria: {},
         data: {},
@@ -233,9 +246,9 @@ module NitroKit
           icon: :x,
           variant: :ghost,
           size: :sm,
-          html: with_command(declaration.html, "close"),
+          html: command_attributes(declaration.html, "close", commandfor: element_id(:panel)),
           aria: declaration.aria.merge(label: declaration.label),
-          data: declaration.data,
+          data: command_data(declaration.data, "close"),
           desperately_need_a_class: declaration.css_class
         ),
         :close
@@ -276,17 +289,8 @@ module NitroKit
       raise ArgumentError, "Dialog close button must be declared inside the panel block"
     end
 
-    def with_command(html, command, disabled: false)
-      unless html.is_a?(Hash)
-        raise ArgumentError, "html must be a Hash"
-      end
-
-      collision = html.keys.find { |key| %w[command commandfor].include?(key.to_s.downcase) }
-      if collision
-        raise ArgumentError, "#{collision}: is owned by Dialog"
-      end
-
-      disabled ? html : html.merge(command:, commandfor: element_id(:panel))
+    def default_close_label
+      I18n.t("nitro_kit.dialog.close")
     end
   end
 end

data/app/components/nitro_kit/dropdown.rb

@@ -373,15 +373,10 @@ module NitroKit
         "Unknown Dropdown trigger #{name} #{value.inspect}; expected one of: #{choices.map(&:inspect).join(", ")}"
     end
 
-    # Private copy of the AppShell identifier contract. Extract a shared
-    # validator into Component once its owner lands.
     def component_id(value)
       return generated_id if value.nil?
-      return value if value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
 
-      raise ArgumentError,
-        "Dropdown id must be nil or a String starting with a letter or digit and containing " \
-        "only letters, digits, hyphens, and underscores"
+      validate_id!("Dropdown id", value)
     end
 
     def generated_id

data/app/components/nitro_kit/dropzone.rb

@@ -44,7 +44,7 @@ module NitroKit
       name:,
       label: I18n.t("nitro_kit.dropzone.label"),
       description: nil,
-      presentation: :input,
+      presentation: :minimal,
       direct_upload: true,
       multiple: false,
       accept: nil,
@@ -57,8 +57,8 @@ module NitroKit
       data: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
-      @name = form_name(name)
+      @identifier = validate_id!("Dropzone id", id)
+      @name = validate_text!("Dropzone name", name)
       @label = required_text(:label, label)
       @description = optional_text(:description, description)
       @presentation = validate_choice!(:presentation, presentation, PRESENTATIONS)
@@ -127,6 +127,7 @@ module NitroKit
       ) do
         strong(**slot_attributes(:title, attributes: { id: title_id })) { plain(@label) }
         span(**slot_attributes(:instruction)) { plain(I18n.t("nitro_kit.dropzone.prompt")) }
+        span(**slot_attributes(:compact_instruction)) { plain(I18n.t("nitro_kit.dropzone.compact_prompt")) }
 
         if description
           span(**slot_attributes(:description, attributes: { id: description_id })) { plain(description) }
@@ -291,18 +292,6 @@ module NitroKit
       Rails.application.routes.url_helpers
     end
 
-    def component_id(value)
-      return value if value.is_a?(String) && value.present? && !value.match?(/\s/)
-
-      raise ArgumentError, "Dropzone id must be a non-blank String without whitespace"
-    end
-
-    def form_name(value)
-      return value if value.is_a?(String) && value.present?
-
-      raise ArgumentError, "Dropzone name must be a non-blank String"
-    end
-
     def required_text(name, value)
       return value if value.is_a?(String) && value.present?
 

data/app/components/nitro_kit/empty_state.rb

@@ -39,8 +39,8 @@ module NitroKit
 
     attr_reader :level, :variant
 
-    def view_template
-      yield self if block_given?
+    def view_template(&block)
+      collect_declarations(&block)
       require_content!("EmptyState", :title, @title_content)
 
       section(**root_attributes) do
@@ -54,16 +54,19 @@ module NitroKit
     end
 
     def title(text = nil, &block)
+      ensure_collecting!
       @title_content = declare_content(:title, @title_content, text, &block)
       nil
     end
 
     def description(text = nil, &block)
+      ensure_collecting!
       @description_content = declare_content(:description, @description_content, text, &block)
       nil
     end
 
     def icon(component, &content)
+      ensure_collecting!
       unless component.is_a?(NitroKit::Icon)
         raise ArgumentError, "EmptyState icon must be a NitroKit::Icon"
       end
@@ -74,6 +77,7 @@ module NitroKit
     end
 
     def action(component, &content)
+      ensure_collecting!
       unless component.is_a?(NitroKit::Button)
         raise ArgumentError, "EmptyState actions must be NitroKit::Button instances"
       end
@@ -88,6 +92,21 @@ module NitroKit
 
     private
 
+    def collect_declarations
+      return unless block_given?
+
+      @collecting = true
+      yield(self)
+    ensure
+      @collecting = false
+    end
+
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "EmptyState declarations must be inside the render block"
+    end
+
     def render_actions
       div(**slot_attributes(:actions)) do
         @actions.each do |action|

data/app/components/nitro_kit/field.rb

@@ -64,7 +64,7 @@ module NitroKit
       @id = id || form&.field_id(field_name) || default_field_id
       @name = name || form&.field_name(field_name, multiple: @multiple) || default_field_name
       @explicit_value = value
-      @field_label = label.nil? ? derived_label : label
+      @field_label = label.nil? ? UNSET : label
       @field_description = description
       @field_error_messages = Array(errors).compact
       @options = options
@@ -124,7 +124,11 @@ module NitroKit
       )
     end
 
-    attr_reader :as, :form, :name, :id, :field_label, :field_description, :field_error_messages
+    attr_reader :as, :form, :name, :id, :field_description, :field_error_messages
+
+    def field_label
+      @field_label.equal?(UNSET) ? derived_label : @field_label
+    end
 
     def view_template(&block)
       div(**root_attributes) do
@@ -335,17 +339,32 @@ module NitroKit
     end
 
     def rich_text_control(html:, aria:, data:)
+      editor_aria = control_aria(aria)
+      content = annotated_rich_text_content(editor_aria)
+
       render_in_slot(
         RichTextArea.new(
-          @rich_text_content,
+          content,
           html: @control_html.merge(html),
-          aria: control_aria(aria),
+          aria: content.equal?(@rich_text_content) ? editor_aria : {},
           data: @control_data.merge(data)
         ),
         :control
       )
     end
 
+    # The application owns the editor markup, so the control ARIA is injected
+    # into the lexxy-editor tag where assistive technology reads it instead of
+    # landing on the role-less wrapper.
+    def annotated_rich_text_content(aria)
+      return @rich_text_content unless @rich_text_content&.include?("<lexxy-editor")
+
+      attributes = aria.map { |key, value| %(aria-#{key}="#{ERB::Util.html_escape(value)}") }.join(" ")
+      return @rich_text_content if attributes.empty?
+
+      @rich_text_content.sub("<lexxy-editor", "<lexxy-editor #{attributes}").html_safe
+    end
+
     def checkbox_control(html:, aria:, data:)
       render_in_slot(
         Checkbox.new(
@@ -360,7 +379,7 @@ module NitroKit
           disabled: @disabled,
           required: @required,
           control_html: @control_html.merge(html),
-          control_aria: control_aria(aria),
+          control_aria: labeled_control_aria(aria),
           control_data: @control_data.merge(data)
         ),
         :control
@@ -381,7 +400,7 @@ module NitroKit
           disabled: @disabled,
           required: @required,
           control_html: @control_html.merge(html),
-          control_aria: switch_aria(aria),
+          control_aria: labeled_control_aria(aria),
           control_data: @control_data.merge(data)
         ),
         :control
@@ -401,7 +420,7 @@ module NitroKit
           disabled: @disabled || choice.disabled,
           required: @required,
           control_html: @control_html.merge(html),
-          control_aria: control_aria(aria),
+          control_aria: labeled_control_aria(aria),
           control_data: @control_data.merge(data)
         ),
         :control
@@ -420,7 +439,9 @@ module NitroKit
           disabled: @disabled,
           required: @required,
           html: @control_html.merge(html),
-          aria: control_aria(aria),
+          # The fieldset's implicit group role does not support aria-invalid,
+          # so the error state stays on the error list it references.
+          aria: control_aria(aria).except(:invalid),
           data: @control_data.merge(data)
         ),
         :control
@@ -443,13 +464,15 @@ module NitroKit
       ).compact
     end
 
-    def switch_aria(extra)
+    def labeled_control_aria(extra)
       attributes = control_aria(extra)
       return attributes unless field_label == false
       return attributes if attributes.keys.any? { |key| %w[label labelledby].include?(key.to_s.delete("_-")) }
 
       accessible_name = derived_label || name.to_s.humanize.presence
-      raise ArgumentError, "an unlabeled switch requires a field name or control ARIA label" unless accessible_name
+      unless accessible_name
+        raise ArgumentError, "an unlabeled #{as.to_s.tr("_", " ")} requires a field name or control ARIA label"
+      end
 
       attributes.merge(label: accessible_name)
     end
@@ -460,10 +483,11 @@ module NitroKit
     end
 
     def derived_label
+      return @derived_label if defined?(@derived_label)
       return unless @field_name
 
       object = form&.object
-      if object && object.class.respond_to?(:human_attribute_name)
+      @derived_label = if object && object.class.respond_to?(:human_attribute_name)
         object.class.human_attribute_name(@field_name)
       else
         @field_name.humanize

data/app/components/nitro_kit/form_builder.rb

@@ -66,7 +66,6 @@ module NitroKit
       &block
     )
       as = validate_as!(as)
-      label = default_label_for(field_name) if label.nil?
       errors ||= errors_for(field_name)
       control_html = merge_control_boundary(:html, control_html, html)
       control_aria = merge_control_boundary(:aria, control_aria, aria)
@@ -116,7 +115,7 @@ module NitroKit
       id: nil,
       label: I18n.t("nitro_kit.dropzone.label"),
       description: nil,
-      presentation: :input,
+      presentation: :minimal,
       direct_upload: true,
       multiple: false,
       accept: nil,

data/app/components/nitro_kit/progressive_image.rb

@@ -31,10 +31,10 @@ module NitroKit
         component: :progressive_image,
         attributes: {
           id:,
-          aria: { busy: @attached ? true : nil },
           data: {
             state: @attached ? "loading" : "empty",
-            controller: @attached ? "nk--progressive-image" : nil
+            controller: @attached ? "nk--progressive-image" : nil,
+            action: @attached ? "turbo:before-cache@document->nk--progressive-image#prepareForCache" : nil
           }.compact
         },
         html:,