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

data/app/components/nitro_kit/accordion.rb

@@ -13,7 +13,7 @@ module NitroKit
       data: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
+      @identifier = validate_id!("Accordion id", id)
       @mode = validate_choice!(:mode, mode, MODES)
       @items = []
 
@@ -152,11 +152,5 @@ module NitroKit
 
       raise ArgumentError, "Accordion #{name} must be true or false"
     end
-
-    def component_id(value)
-      return value if value.is_a?(String) && value.present? && !value.match?(/\s/)
-
-      raise ArgumentError, "Accordion id must be a non-blank String without whitespace"
-    end
   end
 end

data/app/components/nitro_kit/app_navigation.rb

@@ -223,8 +223,7 @@ module NitroKit
             :item_link,
             attributes: {
               href: entry.href,
-              aria: { current: entry.current ? "page" : nil },
-              data: { state: entry.current ? "current" : "default" }
+              aria: { current: entry.current ? "page" : nil }
             },
             html: entry.html,
             aria: entry.aria,

data/app/components/nitro_kit/app_shell.rb

@@ -21,7 +21,7 @@ module NitroKit
       data: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
+      @identifier = validate_id!("AppShell id", id)
       @layout = validate_choice!(:layout, layout, LAYOUTS)
       @skip_link_label = validate_label!(:skip_link_label, skip_link_label)
       @open_navigation_label = validate_label!(:open_navigation_label, open_navigation_label)
@@ -212,12 +212,6 @@ module NitroKit
       "#{identifier}-main"
     end
 
-    def component_id(value)
-      return value if value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
-
-      raise ArgumentError, "AppShell id must be a fragment-safe String using letters, numbers, underscores, or hyphens"
-    end
-
     def validate_label!(name, value)
       return value if value.is_a?(String) && !value.strip.empty?
 

data/app/components/nitro_kit/appearance_picker.rb

@@ -20,7 +20,7 @@ module NitroKit
       data: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
+      @identifier = validate_id!("AppearancePicker id", id)
       @label = validate_label!(label)
       @presentation = validate_choice!(:presentation, presentation, PRESENTATIONS)
       @preference = validate_choice!(:preference, preference, PREFERENCES)
@@ -137,16 +137,6 @@ module NitroKit
       "#{identifier}-#{preference}"
     end
 
-    # Private copy of the AppShell identifier contract. Extract a shared
-    # validator into Component once its owner lands.
-    def component_id(value)
-      return value if value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
-
-      raise ArgumentError,
-        "AppearancePicker id must be a String starting with a letter or digit and containing " \
-        "only letters, digits, hyphens, and underscores"
-    end
-
     def validate_label!(value)
       return value if value.is_a?(String) && value.present?
 

data/app/components/nitro_kit/avatar.rb

@@ -9,6 +9,7 @@ module NitroKit
       alt: "",
       fallback: nil,
       size: :md,
+      decorative: false,
       loading: "lazy",
       decoding: "async",
       id: nil,
@@ -18,12 +19,16 @@ module NitroKit
       desperately_need_a_class: nil
     )
       raise ArgumentError, "alt must be a String" unless alt.is_a?(String)
+      @decorative = validate_boolean!(:decorative, decorative)
       unless fallback.nil? || fallback.is_a?(String)
         raise ArgumentError, "fallback must be a String or nil"
       end
 
       @src = src
       @alt = alt
+      if src? && alt.empty? && !@decorative
+        raise ArgumentError, "Avatar images require alt: text unless decorative: true"
+      end
       @fallback = fallback || initials_for(alt)
       @size = validate_choice!(:size, size, SIZES)
       root_aria = fallback_aria(aria)
@@ -49,7 +54,7 @@ module NitroKit
       }
     end
 
-    attr_reader :src, :alt, :fallback, :size
+    attr_reader :src, :alt, :fallback, :size, :decorative
 
     def view_template
       span(**root_attributes) do

data/app/components/nitro_kit/avatar_stack.rb

@@ -61,6 +61,7 @@ module NitroKit
       src: nil,
       alt: "",
       fallback: nil,
+      decorative: false,
       loading: "lazy",
       decoding: "async",
       id: nil,
@@ -75,6 +76,7 @@ module NitroKit
         src:,
         alt:,
         fallback:,
+        decorative:,
         size:,
         loading:,
         decoding:,
@@ -156,6 +158,7 @@ module NitroKit
       span(
         **slot_attributes(
           :overflow,
+          attributes: { role: "img" },
           html: declaration.html,
           aria: declaration.aria.merge(
             label: declaration.label || I18n.t("nitro_kit.avatar_stack.overflow", count: declaration.count)

data/app/components/nitro_kit/button_group.rb

@@ -28,9 +28,9 @@ module NitroKit
 
       super(
         component: :button_group,
-        attributes: { id:, role: "group" },
+        attributes: { id:, role: "group", aria: { label: }.compact },
         html:,
-        aria: label ? aria.merge(label:) : aria,
+        aria:,
         data:,
         desperately_need_a_class:
       )

data/app/components/nitro_kit/checkbox.rb

@@ -78,12 +78,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/checkbox_group.rb

@@ -122,30 +122,5 @@ module NitroKit
     def multiple_name(name)
       name.end_with?("[]") ? name : "#{name}[]"
     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/combobox.rb

@@ -22,8 +22,8 @@ module NitroKit
       control_aria: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
-      @name = form_name(name)
+      @identifier = validate_id!("Combobox id", id)
+      @name = validate_text!("Combobox name", name)
       @label = visible_label(label)
       @options = typed_options(options)
       @value = value
@@ -52,7 +52,6 @@ module NitroKit
             controller: "nk--combobox",
             placement: placement_value,
             state: "closed",
-            action: "click@window->nk--combobox#closeFromOutside",
             nk__combobox_open_value: "false",
             nk__combobox_required_value: @required,
             nk__combobox_invalid_selection_value: I18n.t("nitro_kit.combobox.invalid_selection"),
@@ -103,7 +102,7 @@ module NitroKit
               autocomplete: "list",
               controls: listbox_id,
               expanded: false,
-              required: @required
+              required: @required || nil
             ),
             data: {
               nk__combobox_target: "input",
@@ -299,18 +298,6 @@ module NitroKit
       end
     end
 
-    def component_id(value)
-      return value if value.is_a?(String) && value.present? && !value.match?(/\s/)
-
-      raise ArgumentError, "Combobox 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, "Combobox name must be a non-blank String"
-    end
-
     def visible_label(value)
       return value if value == false
       return value if value.is_a?(String) && value.present?

data/app/components/nitro_kit/command_palette.rb

@@ -16,12 +16,6 @@ module NitroKit
     module Validation
       private
 
-      def component_id(value)
-        return value if value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
-
-        raise ArgumentError, "CommandPalette id: must contain only letters, numbers, underscores, and hyphens"
-      end
-
       def required_text(name, value)
         return value if value.is_a?(String) && !value.strip.empty?
 
@@ -30,10 +24,38 @@ module NitroKit
     end
     private_constant :Validation
 
+    module Destinations
+      def destination(
+        label,
+        href:,
+        description: nil,
+        html: {},
+        aria: {},
+        data: {},
+        desperately_need_a_class: nil
+      )
+        ensure_collecting!
+
+        @destinations << Destination.new(
+          label: required_text(:label, label),
+          href: required_text(:href, href),
+          description: validate_optional_text!(:description, description),
+          html:,
+          aria:,
+          data:,
+          css_class: desperately_need_a_class
+        )
+        nil
+      end
+    end
+    private_constant :Destinations
+
     include Validation
+    include Destinations
 
     class Results < Component
       include Validation
+      include Destinations
 
       def initialize(
         id:,
@@ -42,7 +64,7 @@ module NitroKit
         data: {},
         desperately_need_a_class: nil
       )
-        @identifier = component_id(id)
+        @identifier = validate_id!("CommandPalette id:", id)
         @destinations = []
 
         super(
@@ -65,38 +87,16 @@ module NitroKit
         )
       end
 
-      def destination(
-        label,
-        href:,
-        description: nil,
-        html: {},
-        aria: {},
-        data: {},
-        desperately_need_a_class: nil
-      )
-        ensure_collecting!
-
-        @destinations << Destination.new(
-          label: required_text(:label, label),
-          href: required_text(:href, href),
-          description: validate_optional_text!(:description, description),
-          html:,
-          aria:,
-          data:,
-          css_class: desperately_need_a_class
-        )
-        nil
-      end
-
       def view_template(&block)
         @collecting = true
         yield(self) if block
 
         tag(:"turbo-frame", **root_attributes) do
           nav(
-            id: results_id,
-            aria: { labelledby: title_id },
-            data: { slot: "command-palette-results" }
+            **slot_attributes(
+              :results,
+              attributes: { id: results_id, aria: { labelledby: title_id } }
+            )
           ) do
             @destinations.each_with_index { |destination, index| render_destination(destination, index) }
           end
@@ -163,7 +163,7 @@ module NitroKit
       data: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
+      @identifier = validate_id!("CommandPalette id:", id)
       @label = required_text(:label, label)
       @placeholder = required_text(:placeholder, placeholder)
       @empty_text = required_text(:empty_text, empty_text)
@@ -204,29 +204,6 @@ module NitroKit
       end
     end
 
-    def destination(
-      label,
-      href:,
-      description: nil,
-      html: {},
-      aria: {},
-      data: {},
-      desperately_need_a_class: nil
-    )
-      ensure_collecting!
-
-      @destinations << Destination.new(
-        label: required_text(:label, label),
-        href: required_text(:href, href),
-        description: validate_optional_text!(:description, description),
-        html:,
-        aria:,
-        data:,
-        css_class: desperately_need_a_class
-      )
-      nil
-    end
-
     private
 
     def collect_destinations
@@ -250,7 +227,8 @@ module NitroKit
           }.compact,
           data: {
             nk__command_palette_target: "trigger",
-            action: "click->nk--command-palette#open"
+            nk__dialog_command: "show-modal",
+            action: "click->nk--command-palette#openedByTrigger"
           }
         ),
         :trigger
@@ -278,6 +256,7 @@ module NitroKit
               action: [
                 "click->nk--dialog#dismiss",
                 "cancel->nk--dialog#cancel",
+                "close->nk--dialog#restoreFocus",
                 "close->nk--command-palette#closed"
               ].join(" ")
             }
@@ -342,6 +321,7 @@ module NitroKit
           variant: :ghost,
           size: :md,
           html: { command: "close", commandfor: panel_id },
+          data: { nk__dialog_command: "close" },
           aria: { label: @close_label }
         ),
         :close
@@ -392,7 +372,9 @@ module NitroKit
     def root_actions
       actions = [
         "turbo:before-visit@document->nk--command-palette#closeForVisit",
-        "turbo:before-cache@document->nk--command-palette#closeForVisit"
+        "turbo:before-cache@document->nk--command-palette#closeForVisit",
+        "click->nk--dialog#invoke",
+        "turbo:before-cache@document->nk--dialog#closeForCache"
       ]
       actions.prepend("keydown@document->nk--command-palette#shortcut") if @shortcut
       actions.join(" ")

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