nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/choice.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module NitroKit
+  Choice = Data.define(:label, :value, :disabled, :id, :description) do
+    def initialize(label:, value:, disabled: false, id: nil, description: nil)
+      unless disabled == true || disabled == false
+        raise ArgumentError, "disabled must be true or false; received #{disabled.inspect}"
+      end
+      if label.nil? || label.to_s.strip.empty?
+        raise ArgumentError, "choice label cannot be blank"
+      end
+      if value.nil?
+        raise ArgumentError, "choice value cannot be nil"
+      end
+      if id && (!id.is_a?(String) || id.strip.empty?)
+        raise ArgumentError, "choice id must be a non-blank String"
+      end
+      if description && (!description.is_a?(String) || description.strip.empty?)
+        raise ArgumentError, "choice description must be a non-blank String"
+      end
+
+      super(label:, value:, disabled:, id:, description:)
+    end
+
+    def self.coerce(choice)
+      case choice
+      when self
+        choice
+      when Hash
+        attributes = choice.symbolize_keys
+        unknown_keys = attributes.keys - %i[label value disabled id description]
+        if unknown_keys.any?
+          raise ArgumentError, "unknown choice attributes: #{unknown_keys.join(", ")}"
+        end
+        new(
+          label: attributes.fetch(:label),
+          value: attributes.fetch(:value),
+          disabled: attributes.fetch(:disabled, false),
+          id: attributes[:id],
+          description: attributes[:description]
+        )
+      when Array
+        unless choice.length.between?(1, 2)
+          raise ArgumentError,
+            "choice arrays hold a label and an optional value; " \
+            "pass a Hash to declare disabled, id, or description"
+        end
+
+        new(label: choice.fetch(0), value: choice.fetch(1, choice.fetch(0)))
+      else
+        new(label: choice, value: choice)
+      end
+    end
+  end
+end

data/app/components/nitro_kit/combobox.rb

@@ -2,146 +2,333 @@
 
 module NitroKit
   class Combobox < Component
-    def initialize(
-      options: [],
-      id: nil,
-
-      placement: "bottom",
-      tab_inserts_suggestions: true,
-      first_option_selection_mode: "selected",
-      scroll_into_view_options: { block: "nearest", inline: "nearest" },
+    PLACEMENTS = %i[bottom_start bottom_end top_start top_end].freeze
 
-      **attrs
+    def initialize(
+      id:,
+      name:,
+      label:,
+      options:,
+      value: nil,
+      placeholder: nil,
+      include_blank: true,
+      placement: :bottom_start,
+      required: false,
+      disabled: false,
+      autocomplete: "off",
+      html: {},
+      aria: {},
+      data: {},
+      control_aria: {},
+      desperately_need_a_class: nil
     )
-      # floating-ui options
-      @placement = placement
-
-      # combobox-nav options
-      @tab_inserts_suggestions = tab_inserts_suggestions
-      @first_option_selection_mode = first_option_selection_mode
-      @scroll_into_view_options = scroll_into_view_options
-
-      @id = id || "nk--combobox-" + SecureRandom.hex(4)
+      @identifier = component_id(id)
+      @name = form_name(name)
+      @label = visible_label(label)
+      @options = typed_options(options)
+      @value = value
+      @selected_option = selected_option(value)
+      @placeholder = validate_optional_text!(:placeholder, placeholder)
+      @include_blank = validate_blank_option!(include_blank)
+      @placement = validate_choice!(:placement, placement, PLACEMENTS)
+      @required = validate_boolean!(:required, required)
+      @disabled = validate_boolean!(:disabled, disabled)
+      @autocomplete = autocomplete
+      @control_aria = attribute_hash(control_aria, name: "control_aria")
 
-      @options = options
+      if !value.nil? && !@selected_option
+        raise ArgumentError, "Combobox value #{value.inspect} does not match a declared option"
+      end
+      if @label == false && !named_by_control_aria?
+        raise ArgumentError,
+          "a Combobox without label: requires control_aria: { label: } or control_aria: { labelledby: }"
+      end
 
       super(
-        attrs,
-        type: "text",
-        class: input_class,
-        data: {
-          nk__combobox_target: "input",
-          action: %w[
-            focusin->nk--combobox#open
-            focusin@window->nk--combobox#focusShift
-            click@window->nk--combobox#windowClick
-            input->nk--combobox#input
-            keydown.esc->nk--combobox#clear
-            keydown.down->nk--combobox#open
-          ]
+        component: :combobox,
+        attributes: {
+          id: @identifier,
+          data: {
+            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"),
+            nk__combobox_no_results_value: I18n.t("nitro_kit.combobox.no_results"),
+            nk__combobox_results_one_value: I18n.t("nitro_kit.combobox.results.one"),
+            nk__combobox_results_other_value: I18n.t("nitro_kit.combobox.results.other")
+          }
         },
-        aria: {
-          controls: id(:listbox)
-        }
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
       )
     end
 
-    attr_reader(
-      :options,
-      :placement,
-      :tab_inserts_suggestions,
-      :first_option_selection_mode,
-      :scroll_into_view_options
-    )
+    attr_reader :identifier, :name, :label, :options, :value, :placement
 
     def view_template
-      div(
-        class: "isolate",
-        data: {
-          slot: "control",
-          controller: "nk--combobox",
-          nk__combobox_placement_value: placement,
-          nk__combobox_tab_inserts_suggestions_value: tab_inserts_suggestions.to_s,
-          nk__combobox_first_option_selection_mode_value: first_option_selection_mode.to_s,
-          nk__combobox_scroll_into_view_options_value: scroll_into_view_options&.to_json
-        }
+      div(**root_attributes) do
+        render_label
+        render_control
+        render_native_select
+        render_listbox
+        render_status
+      end
+    end
+
+    private
+
+    def render_label
+      return if label == false
+
+      render_in_slot(Label.new(label, for: input_id, id: label_id), :label)
+    end
+
+    def render_control
+      span(**slot_attributes(:control, attributes: { hidden: true }, data: { nk__combobox_target: "control" })) do
+        render_in_slot(
+          Input.new(
+            type: :text,
+            id: input_id,
+            value: @selected_option&.label&.to_s,
+            placeholder: @placeholder,
+            disabled: @disabled,
+            autocomplete: @autocomplete,
+            html: { role: "combobox" },
+            aria: @control_aria.merge(
+              autocomplete: "list",
+              controls: listbox_id,
+              expanded: false,
+              required: @required
+            ),
+            data: {
+              nk__combobox_target: "input",
+              action: [
+                "focus->nk--combobox#open",
+                "input->nk--combobox#filter",
+                "keydown->nk--combobox#navigate",
+                "blur->nk--combobox#validate"
+              ].join(" ")
+            }
+          ),
+          :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") }
+      end
+    end
+
+    def render_native_select
+      render_in_slot(
+        Select.new(
+          options:,
+          id: value_id,
+          name:,
+          value: @selected_option&.value,
+          include_blank: @include_blank,
+          disabled: @disabled,
+          required: @required,
+          autocomplete: @autocomplete,
+          data: { nk__combobox_target: "native" },
+          control_aria: accessible_naming,
+          control_data: { nk__combobox_target: "value" }
+        ),
+        :native
+      )
+    end
+
+    def render_listbox
+      ul(
+        **slot_attributes(
+          :listbox,
+          attributes: {
+            id: listbox_id,
+            role: "listbox",
+            hidden: true,
+            aria: accessible_naming,
+            data: {
+              placement: placement_value,
+              state: "closed",
+              nk__combobox_target: "listbox"
+            }
+          }
+        )
       ) do
-        span(class: wrapper_class) do
-          render(Input.new(**attrs, value: display_value))
-          chevron_icon
+        options.each_with_index { |option, index| render_option(option, index) }
+      end
+    end
+
+    def render_option(option, index)
+      selected = option.equal?(@selected_option)
+
+      li(
+        **slot_attributes(
+          :option,
+          attributes: {
+            id: option_id(index),
+            role: "option",
+            aria: {
+              disabled: option.disabled ? true : nil,
+              selected:,
+              label: option.description ? option.label.to_s : nil,
+              describedby: option.description ? option_description_id(index) : nil
+            }.compact,
+            data: {
+              value: option.value.to_s,
+              state: selected ? "selected" : "unselected",
+              nk__combobox_target: "option",
+              action: option.disabled ? nil : "click->nk--combobox#select pointermove->nk--combobox#activate"
+            }
+          }
+        )
+      ) do
+        span(**slot_attributes(:option_label)) { plain(option.label.to_s) }
+
+        if option.description
+          span(
+            **slot_attributes(:option_description, attributes: { id: option_description_id(index) })
+          ) { plain(option.description) }
         end
+      end
+    end
 
-        # Since a combobox can function like a <select> element where the displayed
-        # value and the form value differ, include the value in a hidden field
-        input(
-          type: "hidden",
-          value: attrs[:value],
-          name: attrs[:name],
-          data: { nk__combobox_target: "hiddenField" }
+    def render_status
+      div(
+        **slot_attributes(
+          :status,
+          attributes: {
+            role: "status",
+            aria: { live: "polite", atomic: "true" },
+            data: { nk__combobox_target: "status" }
+          }
         )
+      )
+    end
+
+    def typed_options(value)
+      unless value.is_a?(Array) && value.any?
+        raise ArgumentError, "Combobox options must be a non-empty Array"
+      end
 
-        ul(
-          role: "listbox",
-          id: id(:listbox),
-          class: list_class,
-          data: { nk__combobox_target: "list", state: "closed" }
-        ) do
-          options.each do |(key, value)|
-            li(
-              role: "option",
-              data: { value: },
-              class: merge_class(option_class)
-            ) { key }
-          end
+      coerced = value.map do |option|
+        unless option.is_a?(Choice) || option.is_a?(Hash) || option.is_a?(Array)
+          raise ArgumentError, "Combobox options must be Choice instances, Hashes, or label/value Arrays"
         end
+
+        Choice.coerce(option)
+      end
+
+      duplicates = coerced.group_by { |option| option.value.to_s }.select { |_key, options| options.many? }
+      if duplicates.any?
+        raise ArgumentError, "Combobox option values must be unique: #{duplicates.keys.join(", ")}"
       end
+
+      coerced.freeze
     end
 
-    private
+    def selected_option(value)
+      return if value.nil?
 
-    def id(suffix)
-      "#{@id}-#{suffix}"
+      options.find { |option| option.value.to_s == value.to_s }
     end
 
-    def display_value
-      selected = options.find do |(key, value)|
-        value.to_s == attrs[:value].to_s
-      end
+    def placement_value
+      placement.to_s.tr("_", "-")
+    end
+
+    def input_id
+      "#{identifier}-input"
+    end
 
-      selected&.first || attrs[:value]
+    def value_id
+      "#{identifier}-value"
     end
 
-    def wrapper_class
-      "inline-grid *:[grid-area:1/1] group/combobox"
+    def listbox_id
+      "#{identifier}-listbox"
     end
 
-    def input_class
-      "pr-8"
+    def option_id(index)
+      "#{identifier}-option-#{index + 1}"
     end
 
-    def list_class
-      [
-        "absolute top-0 left-0 p-1 bg-background rounded-md border shadow-sm w-fit max-w-sm flex-col flex z-10",
-        "max-h-60 overflow-y-auto",
-        "data-[state=closed]:hidden [&:not(:has([role=option]))]:hidden",
-        "[&_[aria-selected]]:bg-muted"
-      ]
+    def option_description_id(index)
+      "#{option_id(index)}-description"
     end
 
-    def option_class
-      "hidden flex-none px-2 py-1 rounded font-medium truncate cursor-pointer hover:bg-muted [&[role=option]]:block"
+    def label_id
+      "#{identifier}-label"
     end
 
-    def chevron_icon
-      svg(
-        class: "size-4 self-center place-self-end mr-2 pointer-events-none text-muted-content group-hover/combobox:text-foreground",
-        viewbox: "0 0 24 24",
-        fill: "none",
-        stroke: "currentColor",
-        stroke_width: 1
-      ) do |svg|
-        svg.path(d: "m6 9 6 6 6-6")
+    def accessible_naming
+      return { labelledby: label_id } unless label == false
+
+      naming = @control_aria.slice(*aria_naming_keys)
+      naming.presence || {}
+    end
+
+    def named_by_control_aria?
+      @control_aria.any? do |key, value|
+        aria_naming_keys.include?(key) && value.to_s.present?
       end
     end
+
+    def aria_naming_keys
+      @control_aria.keys.select do |key|
+        %w[label labelledby].include?(key.to_s.downcase.delete("_-"))
+      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?
+
+      raise ArgumentError, "Combobox label must be a non-blank String or false"
+    end
+
+    def validate_optional_text!(name, value)
+      return if value.nil?
+      return value if value.is_a?(String) && value.present?
+
+      raise ArgumentError, "Combobox #{name} must be a non-blank String or nil"
+    end
+
+    def validate_blank_option!(value)
+      return value if value == true || value == false || value.is_a?(String) && value.present?
+
+      raise ArgumentError, "Combobox include_blank must be true, false, or a non-blank String"
+    end
   end
 end