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

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 = []
 
@@ -106,25 +106,7 @@ module NitroKit
     end
 
     def chevron
-      svg(
-        **slot_attributes(
-          :icon,
-          attributes: {
-            viewbox: "0 0 16 16",
-            width: 16,
-            height: 16,
-            fill: "none",
-            stroke: "currentColor",
-            stroke_width: 1.5,
-            stroke_linecap: "round",
-            stroke_linejoin: "round",
-            focusable: "false",
-            aria: { hidden: true }
-          }
-        )
-      ) do |svg|
-        svg.path(d: "m4 6 4 4 4-4")
-      end
+      render_in_slot(Icon.new(:chevron_down, size: :sm), :icon)
     end
 
     def trigger_id(item)
@@ -152,11 +134,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/alert.rb

@@ -2,17 +2,7 @@
 
 module NitroKit
   class Alert < Component
-    VARIANTS = %i[default info success warning error].freeze
-
-    # The palette family each semantic variant borrows in `palette.css`.
-    # Alert owns this mapping; it is not the Badge color axis.
-    VARIANT_PALETTE = {
-      default: :zinc,
-      info: :blue,
-      success: :green,
-      warning: :amber,
-      error: :red
-    }.freeze
+    VARIANTS = %i[default info success warning destructive].freeze
 
     LIVE_MODES = %i[off polite assertive].freeze
 

data/app/components/nitro_kit/app_navigation.rb

@@ -5,8 +5,8 @@ module NitroKit
     alias_method :html_header, :header
     alias_method :html_footer, :footer
 
-    Item = ::Data.define(:text, :href, :icon, :badge, :current, :html, :aria, :data, :css_class)
-    Section = ::Data.define(:label, :entries)
+    Item = ::Data.define(:text, :href, :icon, :icon_end, :badge, :current, :html, :aria, :data, :css_class)
+    Section = ::Data.define(:label, :entries, :collapsible, :expanded)
     Entry = ::Data.define(:kind)
 
     def initialize(
@@ -78,10 +78,16 @@ module NitroKit
       nil
     end
 
-    def section(label: nil, &content)
+    def section(label: nil, collapsible: false, expanded: true, &content)
       ensure_phase!(:body, :section)
       raise ArgumentError, "AppNavigation section requires a block" unless content
 
+      collapsible = validate_boolean!(:collapsible, collapsible)
+      expanded = validate_boolean!(:expanded, expanded)
+      if collapsible && label.nil?
+        raise ArgumentError, "AppNavigation collapsible section requires a label"
+      end
+
       entries = []
       previous_entries = @entry_target
       previous_phase = @phase
@@ -94,7 +100,12 @@ module NitroKit
         unless entries.any?(Item)
           raise ArgumentError, "AppNavigation section requires at least one item"
         end
-        previous_entries << Section.new(label: validate_optional_text!(:label, label), entries:)
+        previous_entries << Section.new(
+          label: validate_optional_text!(:label, label),
+          entries:,
+          collapsible:,
+          expanded:
+        )
         nil
       ensure
         @entry_target = previous_entries
@@ -106,6 +117,7 @@ module NitroKit
       text,
       href:,
       icon: nil,
+      icon_end: nil,
       badge: nil,
       badge_color: :neutral,
       current: false,
@@ -118,6 +130,7 @@ module NitroKit
       text = validate_text!(:text, text)
       href = validate_text!(:href, href)
       icon = item_icon(icon)
+      icon_end = item_icon(icon_end, name: :icon_end)
       badge = item_badge(badge, badge_color)
       current = validate_boolean!(:current, current)
 
@@ -130,6 +143,7 @@ module NitroKit
         text:,
         href:,
         icon:,
+        icon_end:,
         badge:,
         current:,
         html:,
@@ -205,13 +219,33 @@ module NitroKit
 
     def render_section(entry)
       li(**slot_attributes(:section)) do
-        span(**slot_attributes(:section_label)) { plain(entry.label) } if entry.label
-        ul(**slot_attributes(:section_list, attributes: section_list_attributes(entry))) do
-          entry.entries.each { |child| render_entry(child) }
+        if entry.collapsible
+          details(
+            **slot_attributes(:section_disclosure, attributes: { open: entry.expanded })
+          ) do
+            summary(**slot_attributes(:section_label)) do
+              plain(entry.label)
+              section_chevron
+            end
+            render_section_list(entry)
+          end
+        else
+          span(**slot_attributes(:section_label)) { plain(entry.label) } if entry.label
+          render_section_list(entry)
         end
       end
     end
 
+    def render_section_list(entry)
+      ul(**slot_attributes(:section_list, attributes: section_list_attributes(entry))) do
+        entry.entries.each { |child| render_entry(child) }
+      end
+    end
+
+    def section_chevron
+      render_in_slot(Icon.new(:chevron_down, size: :xs), :section_icon)
+    end
+
     def section_list_attributes(entry)
       entry.label ? { aria: { label: entry.label } } : {}
     end
@@ -223,8 +257,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,
@@ -235,6 +268,7 @@ module NitroKit
           render_in_slot(entry.icon, :item_icon) if entry.icon
           span(**slot_attributes(:item_label)) { plain(entry.text) }
           render_in_slot(entry.badge, :item_badge) if entry.badge
+          render_in_slot(entry.icon_end, :item_icon_end) if entry.icon_end
         end
       end
     end
@@ -278,10 +312,10 @@ module NitroKit
       validate_text!(name, value)
     end
 
-    def item_icon(value)
+    def item_icon(value, name: :icon)
       return if value.nil?
       unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
-        raise ArgumentError, "icon must be a non-blank String or Symbol"
+        raise ArgumentError, "#{name} must be a non-blank String or Symbol"
       end
 
       Icon.new(value, size: :sm)

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

@@ -13,6 +13,7 @@ module NitroKit
     def initialize(
       id:,
       label: I18n.t("nitro_kit.appearance_picker.label"),
+      label_visible: true,
       presentation: :segmented,
       preference: :system,
       html: {},
@@ -20,15 +21,23 @@ module NitroKit
       data: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
+      @identifier = validate_id!("AppearancePicker id", id)
       @label = validate_label!(label)
+      @label_visible = validate_boolean!(:label_visible, label_visible)
       @presentation = validate_choice!(:presentation, presentation, PRESENTATIONS)
       @preference = validate_choice!(:preference, preference, PREFERENCES)
+      if !@label_visible && @presentation != :segmented
+        raise ArgumentError,
+          "AppearancePicker label_visible: false requires the segmented presentation"
+      end
 
       super(
         component: :appearance_picker,
         attributes: {
           id: @identifier,
+          # Browsers give legends special layout, so a hidden label omits the
+          # element entirely and the fieldset keeps its name through ARIA.
+          aria: @label_visible ? {} : { label: @label },
           data: {
             controller: "nk--appearance",
             presentation: @presentation,
@@ -50,7 +59,7 @@ module NitroKit
       return render_dropdown if @presentation == :dropdown
 
       fieldset(**root_attributes) do
-        legend(**slot_attributes(:legend)) { plain(@label) }
+        legend(**slot_attributes(:legend)) { plain(@label) } if @label_visible
         div(**slot_attributes(:options)) do
           PREFERENCES.each { |preference| render_option(preference) }
         end
@@ -137,16 +146,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/badge.rb

@@ -4,16 +4,25 @@ module NitroKit
   class Badge < Component
     VARIANTS = %i[default outline].freeze
     SIZES = %i[xs sm md].freeze
-    COLORS = %i[
-      zinc red orange amber yellow lime green emerald teal cyan sky blue indigo
-      violet purple fuchsia pink rose neutral info success warning danger
+    # Two axes on one option, both public and both themeable.
+    #
+    # The semantic families follow the `--nk-palette-{family}` tint roles, so
+    # they move with an application's brand: retheme `--nk-palette-destructive` and
+    # every `destructive` badge follows. The decorative hues follow the
+    # `--nk-palette-{hue}` roles and stay the color they name, for categorical
+    # labelling where meaning is not the point.
+    SEMANTIC_COLORS = %i[neutral info success warning destructive].freeze
+    PALETTE_COLORS = %i[
+      red orange amber yellow lime green emerald teal cyan sky blue indigo
+      violet purple fuchsia pink rose
     ].freeze
+    COLORS = (PALETTE_COLORS + SEMANTIC_COLORS).freeze
 
     def initialize(
       text = nil,
       variant: :default,
       size: :md,
-      color: :zinc,
+      color: :neutral,
       id: nil,
       html: {},
       aria: {},

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",
@@ -118,23 +117,7 @@ module NitroKit
           :input
         )
 
-        svg(
-          **slot_attributes(
-            :icon,
-            attributes: {
-              viewbox: "0 0 16 16",
-              width: 16,
-              height: 16,
-              fill: "none",
-              stroke: "currentColor",
-              stroke_width: 1.5,
-              stroke_linecap: "round",
-              stroke_linejoin: "round",
-              focusable: "false",
-              aria: { hidden: true }
-            }
-          )
-        ) { |svg| svg.path(d: "m4 6 4 4 4-4") }
+        render_in_slot(Icon.new(:chevron_down, size: :sm), :icon)
       end
     end
 
@@ -299,18 +282,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
@@ -276,8 +254,10 @@ module NitroKit
               nk__dialog_target: "panel",
               nk__command_palette_target: "panel",
               action: [
+                "command->nk--command-palette#guardOpen",
                 "click->nk--dialog#dismiss",
                 "cancel->nk--dialog#cancel",
+                "close->nk--dialog#restoreFocus",
                 "close->nk--command-palette#closed"
               ].join(" ")
             }
@@ -342,6 +322,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 +373,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(" ")