nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.3

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

@@ -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)

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:,

data/app/components/nitro_kit/radio_button.rb

@@ -67,12 +67,15 @@ module NitroKit
           render_in_slot(Label.new(for: id), :label) do
             render_control
             span(**slot_attributes(:indicator), aria: { hidden: "true" })
-            span(**slot_attributes(:content)) do
-              span(**slot_attributes(:label_text)) { text_or_block(label, &block) }
-              span(**slot_attributes(:description, attributes: { id: description_id })) { plain(description) } if description
-            end
+            span(**slot_attributes(:label_text)) { text_or_block(label, &block) }
           end
         end
+
+        # The description stays outside the label so aria-describedby carries it
+        # instead of it joining the control's accessible name.
+        if description
+          span(**slot_attributes(:description, attributes: { id: description_id })) { plain(description) }
+        end
       end
     end
 

data/app/components/nitro_kit/radio_button_group.rb

@@ -99,30 +99,5 @@ module NitroKit
     def selected?(choice)
       !value.nil? && value.to_s == choice.value.to_s
     end
-
-    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_text!(name, text)
-      return text if text.is_a?(String) && !text.strip.empty?
-
-      raise ArgumentError, "#{name} must be a non-blank String"
-    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
   end
 end

data/app/components/nitro_kit/select.rb

@@ -26,7 +26,7 @@ module NitroKit
       @option_tags = validate_option_tags!(option_tags)
       @value = value
       @include_blank = validate_blank_option!(include_blank)
-      @prompt = validate_optional_text!(:prompt, prompt)
+      @prompt = validate_prompt!(prompt)
       if @include_blank && @prompt
         raise ArgumentError, "include_blank: and prompt: are mutually exclusive"
       end
@@ -151,11 +151,11 @@ module NitroKit
       raise ArgumentError, "include_blank must be true, false, nil, or a String"
     end
 
-    def validate_optional_text!(name, value)
+    def validate_prompt!(value)
       return if value.nil? || value == false
       return value if value.is_a?(String) && !value.strip.empty?
 
-      raise ArgumentError, "#{name} must be a non-blank String, false, or nil"
+      raise ArgumentError, "prompt must be a non-blank String, false, or nil"
     end
   end
 end

data/app/components/nitro_kit/settings_layout.rb

@@ -2,7 +2,7 @@
 
 module NitroKit
   class SettingsLayout < Component
-    Item = ::Data.define(:text, :href, :icon, :current)
+    Item = ::Data.define(:text, :href, :icon, :current, :html, :aria, :data, :css_class)
 
     def initialize(id: nil, html: {}, aria: {}, data: {}, desperately_need_a_class: nil)
       @label = nil
@@ -42,7 +42,16 @@ module NitroKit
       nil
     end
 
-    def item(text, href:, icon: nil, current: false)
+    def item(
+      text,
+      href:,
+      icon: nil,
+      current: false,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
       ensure_phase!(:navigation, :item)
       text = validate_text!(:text, text)
       href = validate_text!(:href, href)
@@ -54,7 +63,7 @@ module NitroKit
       end
 
       @current_item = true if current
-      @items << Item.new(text:, href:, icon:, current:)
+      @items << Item.new(text:, href:, icon:, current:, html:, aria:, data:, css_class: desperately_need_a_class)
       nil
     end
 
@@ -107,7 +116,11 @@ module NitroKit
               href: item.href,
               aria: { current: item.current ? "page" : nil },
               data: { state: item.current ? "current" : "default" }
-            }
+            },
+            html: item.html,
+            aria: item.aria,
+            data: item.data,
+            desperately_need_a_class: item.css_class
           )
         ) do
           render_in_slot(item.icon, :item_icon) if item.icon

data/app/components/nitro_kit/{form_section.rb → settings_section.rb}

@@ -1,26 +1,29 @@
 # frozen_string_literal: true
 
 module NitroKit
-  class FormSection < Component
+  class SettingsSection < Component
     Child = Data.define(:component, :content)
+    TITLE_LEVELS = (1..6).freeze
 
     def initialize(
       title: nil,
       description: nil,
+      level: 2,
       id: nil,
       html: {},
       aria: {},
       data: {},
       desperately_need_a_class: nil
     )
+      @title_level = validate_choice!(:level, level, TITLE_LEVELS)
       @title_content = content_from_keyword(:title, title)
       @description_content = content_from_keyword(:description, description)
       @status = nil
       @form = nil
-      @title_id = "#{id || "nk-form-section-#{SecureRandom.hex(4)}"}-title"
+      @title_id = "#{id || "nk-settings-section-#{SecureRandom.hex(4)}"}-title"
 
       super(
-        component: :form_section,
+        component: :settings_section,
         attributes: { id:, aria: { labelledby: @title_id } }.compact,
         html:,
         aria:,
@@ -31,12 +34,15 @@ module NitroKit
 
     def view_template
       yield self if block_given?
-      require_content!("FormSection", :title, @title_content)
-      raise ArgumentError, "FormSection requires exactly one form" unless @form
+      require_content!("SettingsSection", :title, @title_content)
+      raise ArgumentError, "SettingsSection requires exactly one form" unless @form
 
       section(**root_attributes) do
         header(**slot_attributes(:header)) do
-          h2(**slot_attributes(:title, attributes: { id: @title_id })) do
+          public_send(
+            :"h#{@title_level}",
+            **slot_attributes(:title, attributes: { id: @title_id })
+          ) do
             render_deferred_content(@title_content)
           end
           if @description_content
@@ -48,7 +54,8 @@ module NitroKit
       end
     end
 
-    def title(text = nil, &block)
+    def title(text = nil, level: nil, &block)
+      @title_level = validate_choice!(:level, level, TITLE_LEVELS) if level
       @title_content = declare_content(:title, @title_content, text, &block)
       nil
     end
@@ -60,17 +67,17 @@ module NitroKit
 
     def status(component, &content)
       unless component.is_a?(NitroKit::Alert)
-        raise ArgumentError, "FormSection status must be a NitroKit::Alert"
+        raise ArgumentError, "SettingsSection status must be a NitroKit::Alert"
       end
-      raise ArgumentError, "FormSection accepts at most one status" if @status
+      raise ArgumentError, "SettingsSection accepts at most one status" if @status
 
       @status = Child.new(component:, content:)
       nil
     end
 
     def form(&content)
-      raise ArgumentError, "FormSection form requires a block" unless content
-      raise ArgumentError, "FormSection accepts exactly one form" if @form
+      raise ArgumentError, "SettingsSection form requires a block" unless content
+      raise ArgumentError, "SettingsSection accepts exactly one form" if @form
 
       @form = content
       nil