nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/select.rb

@@ -2,95 +2,160 @@
 
 module NitroKit
   class Select < Component
-    def initialize(options = nil, value: nil, include_empty: false, prompt: nil, index: nil, **attrs)
-      @options = options
-      @value = value&.to_s
-      @include_empty = include_empty
-      @prompt = prompt
-      @index = index
+    def initialize(
+      options: [],
+      option_tags: nil,
+      id: nil,
+      name: nil,
+      value: nil,
+      include_blank: nil,
+      prompt: nil,
+      disabled: false,
+      required: false,
+      multiple: false,
+      autocomplete: nil,
+      html: {},
+      aria: {},
+      data: {},
+      control_html: {},
+      control_aria: {},
+      control_data: {},
+      desperately_need_a_class: nil
+    )
+      @options = Array(options).map { |choice| Choice.coerce(choice) }.freeze
+      @option_tags = validate_option_tags!(option_tags)
+      @value = value
+      @include_blank = validate_blank_option!(include_blank)
+      @prompt = validate_optional_text!(:prompt, prompt)
+      if @include_blank && @prompt
+        raise ArgumentError, "include_blank: and prompt: are mutually exclusive"
+      end
+      @disabled = validate_boolean!(:disabled, disabled)
+      @required = validate_boolean!(:required, required)
+      @multiple = validate_boolean!(:multiple, multiple)
+      @name = multiple_name(name)
+      @id = id
+      @autocomplete = autocomplete
+      @control_html = control_html
+      @control_aria = control_aria
+      @control_data = control_data
+
+      if @option_tags && @options.any?
+        raise ArgumentError, "options and option_tags are mutually exclusive"
+      end
 
       super(
-        attrs,
-        class: wrapper_class
+        component: :select,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
       )
     end
 
-    attr_reader :value, :options, :include_empty, :prompt, :index
+    attr_reader :options, :value, :include_blank, :prompt, :name, :id
 
     def view_template
-      span(class: wrapper_class, data: { slot: "control" }) do
-        select(**attrs, class: select_class) do
-          if include_empty
-            blank_text = if include_empty.is_a?(String)
-              include_empty
-            elsif @prompt
-              @prompt
-            else
-              ""
-            end
-
-            html_option(value: "", selected: @value == "") { blank_text }
-          end
+      span(**root_attributes) do
+        select(**control_attributes) do
+          render_blank_option if include_blank
+          render_prompt_option if prompt && selected_values.empty?
 
-          if options
-            options.each do |opt|
-              if opt.is_a?(Array) && opt.length >= 2
-                html_option(value: opt[1], selected: @value == opt[1].to_s) { opt[0] }
-              else
-                # Handle simple strings - use as both label and value
-                html_option(value: opt.to_s, selected: @value == opt.to_s) { opt.to_s }
-              end
-            end
+          if @option_tags
+            raw safe(@option_tags)
           else
-            yield if block_given?
+            options.each { |choice| render_option(choice) }
           end
         end
 
-        chevron_icon
+        render_toggle_icon
       end
     end
 
-    alias :html_option :option
+    private
 
-    def option(text = nil, value = nil, **attrs, &block)
-      builder do
-        value ||= text
+    def render_toggle_icon
+      return if @multiple
 
-        html_option(value:, selected: @value == value.to_s, **attrs) do
-          if block_given?
-            yield
-          else
-            text
-          end
-        end
+      svg(
+        **slot_attributes(
+          :icon,
+          attributes: {
+            viewbox: "0 0 20 20",
+            fill: "none",
+            stroke: "currentColor",
+            stroke_width: 1.5,
+            aria: { hidden: true }
+          }
+        )
+      ) do |icon|
+        icon.path(d: "m6.5 8 3.5 3.5L13.5 8", stroke_linecap: "round", stroke_linejoin: "round")
       end
     end
 
-    private
+    def control_attributes
+      slot_attributes(
+        :control,
+        attributes: {
+          id:,
+          name:,
+          disabled: @disabled,
+          required: @required,
+          multiple: @multiple,
+          autocomplete: @autocomplete
+        }.compact,
+        html: @control_html,
+        aria: @control_aria,
+        data: @control_data
+      )
+    end
 
-    def wrapper_class
-      "w-fit inline-grid *:[grid-area:1/1] group/select"
+    def render_blank_option
+      text = include_blank == true ? "" : include_blank
+      option(value: "", selected: selected_values.empty?) { plain(text.to_s) }
     end
 
-    def select_class
-      [
-        "appearance-none bg-background text-foreground rounded-md border px-3 py-2 pr-10 w-full",
-        # Focus
-        "focus:outline-none ring-ring ring-offset-2 ring-offset-background focus-visible:ring-2"
-      ]
+    def render_prompt_option
+      option(value: "", selected: true) { plain(prompt) }
     end
 
-    def chevron_icon
-      svg(
-        class: "size-4 self-center place-self-end mr-1.5 text-muted-content pointer-events-none group-hover/select:text-foreground",
-        viewbox: "0 0 24 24",
-        fill: "none",
-        stroke: "currentColor",
-        stroke_width: 1
-      ) do |svg|
-        svg.path(d: "m7 15 5 5 5-5")
-        svg.path(d: "m7 9 5-5 5 5")
-      end
+    def render_option(choice)
+      option(
+        id: choice.id,
+        value: choice.value,
+        selected: selected_values.include?(choice.value.to_s),
+        disabled: choice.disabled
+      ) { plain(choice.label.to_s) }
+    end
+
+    def selected_values
+      @selected_values ||= Array(value).compact.map(&:to_s)
+    end
+
+    def multiple_name(name)
+      return name unless @multiple && name && !name.end_with?("[]")
+
+      "#{name}[]"
+    end
+
+    def validate_option_tags!(option_tags)
+      return if option_tags.nil?
+      return option_tags if option_tags.is_a?(ActiveSupport::SafeBuffer)
+
+      raise ArgumentError, "option_tags must be an ActiveSupport::SafeBuffer"
+    end
+
+    def validate_blank_option!(value)
+      return value if value.nil? || value == true || value == false || value.is_a?(String)
+
+      raise ArgumentError, "include_blank must be true, false, nil, or a String"
+    end
+
+    def validate_optional_text!(name, 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"
     end
   end
 end

data/app/components/nitro_kit/settings_layout.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class SettingsLayout < Component
+    Item = ::Data.define(:text, :href, :icon, :current)
+
+    def initialize(id: nil, html: {}, aria: {}, data: {}, desperately_need_a_class: nil)
+      @label = nil
+      @items = []
+      @content = nil
+      @phase = nil
+      @navigation_declared = false
+      @current_item = false
+
+      super(
+        component: :settings_layout,
+        attributes: { id: }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    def view_template(&declarations)
+      collect_regions(&declarations)
+
+      div(**root_attributes) do
+        render_navigation
+        render_content
+      end
+    end
+
+    def navigation(label:, &declarations)
+      ensure_phase!(:structure, :navigation)
+      raise ArgumentError, "SettingsLayout accepts exactly one navigation region" if @navigation_declared
+      raise ArgumentError, "SettingsLayout navigation requires a block" unless declarations
+
+      @label = validate_text!(:label, label)
+      @navigation_declared = true
+      collect_items(&declarations)
+      nil
+    end
+
+    def item(text, href:, icon: nil, current: false)
+      ensure_phase!(:navigation, :item)
+      text = validate_text!(:text, text)
+      href = validate_text!(:href, href)
+      icon = item_icon(icon)
+      current = validate_boolean!(:current, current)
+
+      if current && @current_item
+        raise ArgumentError, "SettingsLayout accepts at most one current item"
+      end
+
+      @current_item = true if current
+      @items << Item.new(text:, href:, icon:, current:)
+      nil
+    end
+
+    def content(&block)
+      ensure_phase!(:structure, :content)
+      raise ArgumentError, "SettingsLayout accepts exactly one content region" if @content
+      raise ArgumentError, "SettingsLayout content requires a block" unless block
+
+      @content = block
+      nil
+    end
+
+    private
+
+    def collect_regions
+      raise ArgumentError, "SettingsLayout requires a declaration block" unless block_given?
+
+      @phase = :structure
+      output = capture(self) { |layout| yield layout }
+      reject_rendered_output!(:structure, output)
+      raise ArgumentError, "SettingsLayout requires one navigation region" unless @navigation_declared
+      raise ArgumentError, "SettingsLayout requires one content region" unless @content
+    ensure
+      @phase = nil
+    end
+
+    def collect_items(&declarations)
+      @phase = :navigation
+      output = capture(self, &declarations)
+      reject_rendered_output!(:navigation, output)
+      raise ArgumentError, "SettingsLayout navigation requires at least one item" if @items.empty?
+    ensure
+      @phase = :structure
+    end
+
+    def render_navigation
+      nav(**slot_attributes(:navigation, attributes: { aria: { label: @label } })) do
+        ul(**slot_attributes(:items)) do
+          @items.each { |item| render_item(item) }
+        end
+      end
+    end
+
+    def render_item(item)
+      li(**slot_attributes(:item)) do
+        a(
+          **slot_attributes(
+            :item_link,
+            attributes: {
+              href: item.href,
+              aria: { current: item.current ? "page" : nil },
+              data: { state: item.current ? "current" : "default" }
+            }
+          )
+        ) do
+          render_in_slot(item.icon, :item_icon) if item.icon
+          plain(item.text)
+        end
+      end
+    end
+
+    def render_content
+      div(**slot_attributes(:content)) { render(@content) }
+    end
+
+    def ensure_phase!(expected, declaration)
+      return if @phase == expected
+
+      location = expected == :structure ? "the render block" : "the navigation block"
+      raise ArgumentError, "SettingsLayout #{declaration} must be declared directly inside #{location}"
+    end
+
+    def reject_rendered_output!(location, output)
+      return if output.empty?
+
+      raise ArgumentError, "SettingsLayout #{location} accepts declarations, not rendered content"
+    end
+
+    def item_icon(value)
+      return if value.nil?
+
+      unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
+        raise ArgumentError, "SettingsLayout icon must be a non-blank String or Symbol"
+      end
+
+      Icon.new(value, size: :sm)
+    end
+
+    def validate_text!(name, value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, "SettingsLayout #{name} must be a non-blank String"
+    end
+  end
+end

data/app/components/nitro_kit/sheet.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class Sheet < Component
+    SIDES = %i[left right].freeze
+    SIZES = %i[sm md lg].freeze
+
+    Trigger = Data.define(:text, :variant, :size, :icon, :icon_end, :label, :disabled, :html, :aria, :data, :content)
+    private_constant :Trigger
+
+    Panel = Data.define(:title, :description, :content)
+    private_constant :Panel
+
+    def initialize(
+      id:,
+      side: :right,
+      size: :md,
+      close_label: I18n.t("nitro_kit.sheet.close"),
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      unless id.is_a?(String) && id.present? && !id.match?(/\s/)
+        raise ArgumentError, "Sheet id: must be a non-blank String without whitespace"
+      end
+      unless close_label.is_a?(String) && close_label.present?
+        raise ArgumentError, "Sheet close_label: must be a non-blank String"
+      end
+
+      @id = id
+      @side = validate_choice!(:side, side, SIDES)
+      @size = validate_choice!(:size, size, SIZES)
+      @close_label = close_label
+
+      super(
+        component: :sheet,
+        attributes: {
+          id:,
+          data: {
+            controller: "nk--dialog",
+            side: @side,
+            nk__dialog_dismissible_value: true
+          }
+        },
+        html:,
+        aria:,
+        data:,
+        size:,
+        desperately_need_a_class:
+      )
+    end
+
+    attr_reader :id, :side, :size
+
+    def view_template(&declarations)
+      collect_declarations(&declarations)
+
+      div(**root_attributes) do
+        render_trigger
+        render_panel
+      end
+    end
+
+    def trigger(
+      text = nil,
+      variant: :default,
+      size: :md,
+      icon: nil,
+      icon_end: nil,
+      label: nil,
+      disabled: false,
+      html: {},
+      aria: {},
+      data: {},
+      &content
+    )
+      ensure_collecting!
+      raise ArgumentError, "Sheet accepts exactly one trigger" if @trigger
+
+      @trigger = Trigger.new(
+        text:,
+        variant:,
+        size:,
+        icon:,
+        icon_end:,
+        label:,
+        disabled: validate_boolean!(:disabled, disabled),
+        html:,
+        aria:,
+        data:,
+        content:
+      )
+      nil
+    end
+
+    def panel(title:, description: nil, &content)
+      ensure_collecting!
+      raise ArgumentError, "Sheet accepts exactly one panel" if @panel
+      unless title.is_a?(String) && title.present?
+        raise ArgumentError, "Sheet title: must be a non-blank String"
+      end
+      unless description.nil? || (description.is_a?(String) && description.present?)
+        raise ArgumentError, "Sheet description: must be nil or a non-blank String"
+      end
+
+      @panel = Panel.new(title:, description:, content:)
+      nil
+    end
+
+    private
+
+    def collect_declarations
+      raise ArgumentError, "Sheet requires a declaration block" unless block_given?
+
+      @collecting = true
+      yield(self)
+      raise ArgumentError, "Sheet requires exactly one trigger" unless @trigger
+      raise ArgumentError, "Sheet requires exactly one panel" unless @panel
+    ensure
+      @collecting = false
+    end
+
+    def render_trigger
+      button = Button.new(
+        @trigger.text,
+        variant: @trigger.variant,
+        size: @trigger.size,
+        icon: @trigger.icon,
+        icon_end: @trigger.icon_end,
+        label: @trigger.label,
+        disabled: @trigger.disabled,
+        html: command_attributes(@trigger.html, "show-modal", disabled: @trigger.disabled),
+        aria: @trigger.aria.merge(haspopup: "dialog"),
+        data: @trigger.data
+      )
+
+      render_in_slot(button, :trigger, &@trigger.content)
+    end
+
+    def render_panel
+      dialog(
+        **slot_attributes(
+          :panel,
+          attributes: {
+            id: panel_id,
+            closedby: "any",
+            aria: {
+              labelledby: title_id,
+              describedby: @panel.description ? description_id : nil
+            }.compact,
+            data: {
+              nk__dialog_target: "panel",
+              action: "click->nk--dialog#dismiss cancel->nk--dialog#cancel"
+            }
+          }
+        )
+      ) do
+        render_close
+        h2(**slot_attributes(:title, attributes: { id: title_id })) { @panel.title }
+        if @panel.description
+          p(**slot_attributes(:description, attributes: { id: description_id })) { @panel.description }
+        end
+        div(**slot_attributes(:body)) { render(@panel.content) } if @panel.content
+      end
+    end
+
+    def render_close
+      render_in_slot(
+        Button.new(
+          icon: :x,
+          label: @close_label,
+          variant: :ghost,
+          size: :sm,
+          html: command_attributes({}, "close")
+        ),
+        :close
+      )
+    end
+
+    def command_attributes(html, command, disabled: false)
+      unless html.is_a?(Hash)
+        raise ArgumentError, "html must be a Hash"
+      end
+      if html.keys.any? { |key| %w[command commandfor].include?(key.to_s.downcase) }
+        raise ArgumentError, "command and commandfor are owned by Sheet"
+      end
+
+      disabled ? html : html.merge(command:, commandfor: panel_id)
+    end
+
+    def panel_id = "#{id}-panel"
+    def title_id = "#{id}-title"
+    def description_id = "#{id}-description"
+
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "Sheet declarations must be inside the render block"
+    end
+  end
+end

data/app/components/nitro_kit/stat_grid.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class StatGrid < Component
+    DEFAULT_COLUMNS = "1 sm:2 lg:3"
+    Stat = Data.define(:key, :label, :value, :detail)
+
+    def initialize(
+      cols: DEFAULT_COLUMNS,
+      gap: 4,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @stats = []
+      @grid = Grid.new(cols:, gap:)
+
+      super(
+        component: :stat_grid,
+        attributes: { id: }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    def view_template
+      yield self if block_given?
+      raise ArgumentError, "StatGrid requires at least one stat" if @stats.empty?
+
+      div(**root_attributes) do
+        render_in_slot(@grid, :grid) do
+          html_dl(**slot_attributes(:list)) do
+            @stats.each { |stat| render_stat(stat) }
+          end
+        end
+      end
+    end
+
+    def stat(key:, label:, value:, detail: nil)
+      key = normalize_identity(key, name: "stat key")
+      raise ArgumentError, "StatGrid stat keys must be unique: #{key.inspect}" if @stats.any? { |stat| stat.key == key }
+
+      @stats << Stat.new(
+        key:,
+        label: present_text!(:label, label),
+        value: present_text!(:value, value),
+        detail: detail.nil? ? nil : present_text!(:detail, detail)
+      )
+      nil
+    end
+
+    alias :html_dl :dl
+
+    private
+
+    def render_stat(stat)
+      div(**slot_attributes(:stat, attributes: { data: { key: stat.key } })) do
+        dt(**slot_attributes(:label)) { plain(stat.label) }
+        dd(**slot_attributes(:value)) { plain(stat.value) }
+        dd(**slot_attributes(:detail)) { plain(stat.detail) } if stat.detail
+      end
+    end
+
+    def present_text!(name, value)
+      text = value.to_s
+      raise ArgumentError, "StatGrid #{name} must not be blank" if text.strip.empty?
+
+      text
+    end
+  end
+end