nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/avatar_stack.rb

@@ -2,22 +2,168 @@
 
 module NitroKit
   class AvatarStack < Component
-    def initialize(size: :md, **attrs)
-      @size = size
+    SIZES = Avatar::SIZES
 
-      super(attrs)
+    Overflow = ::Data.define(:count, :label, :html, :aria, :data, :css_class)
+    private_constant :Overflow
+
+    def initialize(
+      label:,
+      size: :md,
+      max: nil,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      unless label.is_a?(String) && label.present?
+        raise ArgumentError, "AvatarStack label: must be a non-blank String"
+      end
+      raise ArgumentError, "aria must be a Hash" unless aria.is_a?(Hash)
+      if aria.keys.any? { |key| key.to_s.downcase.tr("_", "-") == "label" }
+        raise ArgumentError, "AvatarStack group label is owned by label:"
+      end
+      unless max.nil? || (max.is_a?(Integer) && max.positive?)
+        raise ArgumentError, "max must be a positive Integer or nil"
+      end
+
+      @size = validate_choice!(:size, size, SIZES)
+      @max = max
+      @avatars = []
+      @overflow = nil
+
+      super(
+        component: :avatar_stack,
+        attributes: { id:, role: "group" },
+        html:,
+        aria: aria.merge(label:),
+        data:,
+        size:,
+        desperately_need_a_class:
+      )
     end
 
-    attr_reader :size
+    attr_reader :size, :max
+
+    def view_template(&block)
+      collect_declarations(&block)
+
+      visible, hidden = partition_avatars
 
-    def view_template
-      div(**mattr(attrs, class: "flex items-center -space-x-3 [&>div]:ring-2 [&>div]:ring-background")) do
-        yield
+      span(**root_attributes) do
+        visible.each { |avatar| render_in_slot(avatar, :avatar) }
+        render_overflow(overflow_declaration(hidden))
       end
     end
 
-    def avatar(*args, **attrs, &block)
-      render(Avatar.new(*args, size:, **attrs, &block))
+    def avatar(
+      src: nil,
+      alt: "",
+      fallback: nil,
+      loading: "lazy",
+      decoding: "async",
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      ensure_collecting!
+
+      @avatars << Avatar.new(
+        src:,
+        alt:,
+        fallback:,
+        size:,
+        loading:,
+        decoding:,
+        id:,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+      nil
+    end
+
+    def overflow(
+      count,
+      label: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      ensure_collecting!
+      raise ArgumentError, "AvatarStack accepts at most one overflow" if @overflow
+      if max
+        raise ArgumentError, "AvatarStack max: already owns the overflow indicator"
+      end
+      unless count.is_a?(Integer) && count.positive?
+        raise ArgumentError, "count must be a positive Integer"
+      end
+      raise ArgumentError, "label must be a String or nil" unless label.nil? || label.is_a?(String)
+      raise ArgumentError, "aria must be a Hash" unless aria.is_a?(Hash)
+      if aria.keys.any? { |key| key.to_s.downcase.tr("_", "-") == "label" }
+        raise ArgumentError, "AvatarStack overflow label is owned by label:"
+      end
+
+      @overflow = Overflow.new(
+        count:,
+        label:,
+        html:,
+        aria:,
+        data:,
+        css_class: desperately_need_a_class
+      )
+      nil
+    end
+
+    private
+
+    def collect_declarations
+      return unless block_given?
+
+      @collecting = true
+      yield(self)
+    ensure
+      @collecting = false
+    end
+
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "AvatarStack items must be declared inside the render block"
+    end
+
+    def partition_avatars
+      return [ @avatars, [] ] unless max
+
+      [ @avatars.first(max), @avatars.drop(max) ]
+    end
+
+    def overflow_declaration(hidden)
+      return @overflow unless max
+      return nil if hidden.empty?
+
+      Overflow.new(count: hidden.size, label: nil, html: {}, aria: {}, data: {}, css_class: nil)
+    end
+
+    def render_overflow(declaration)
+      return unless declaration
+
+      span(
+        **slot_attributes(
+          :overflow,
+          html: declaration.html,
+          aria: declaration.aria.merge(
+            label: declaration.label || I18n.t("nitro_kit.avatar_stack.overflow", count: declaration.count)
+          ),
+          data: declaration.data,
+          desperately_need_a_class: declaration.css_class
+        )
+      ) { "+#{declaration.count}" }
     end
   end
 end

data/app/components/nitro_kit/badge.rb

@@ -2,100 +2,62 @@
 
 module NitroKit
   class Badge < Component
-    VARIANTS = %i[default outline]
+    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
+    ].freeze
+
+    def initialize(
+      text = nil,
+      variant: :default,
+      size: :md,
+      color: :zinc,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      if !text.nil? && text.to_s.strip.empty?
+        raise ArgumentError, "Badge label content is required"
+      end
 
-    def initialize(text = nil, variant: :default, size: :md, color: :gray, **attrs)
       @text = text
-      @variant = variant
-      @size = size
-      @color = color
+      @variant = validate_choice!(:variant, variant, VARIANTS)
+      @size = validate_choice!(:size, size, SIZES)
+      @color = validate_choice!(:color, color, COLORS)
 
       super(
-        attrs,
-        class: [
-          base_class,
-          variant_class,
-          size_class
-        ]
+        component: :badge,
+        attributes: {
+          id:,
+          data: { color: }
+        },
+        html:,
+        aria:,
+        data:,
+        variant:,
+        size:,
+        desperately_need_a_class:
       )
     end
 
     attr_reader :text, :variant, :size, :color
 
     def view_template(&block)
-      span(**attrs) do
-        text_or_block(text, &block)
+      if block && !text.nil?
+        raise ArgumentError, "Badge accepts label text or block content, not both"
       end
-    end
-
-    private
-
-    def base_class
-      "inline-flex items-center gap-x-1.5 rounded-md font-medium whitespace-nowrap"
-    end
-
-    def variant_class
-      case variant
-      when :default
-        color_class
-      when :outline
-        "border"
-      else
-        raise ArgumentError, "Invalid variant: #{variant}"
+      if !block && text.nil?
+        raise ArgumentError, "Badge label content is required"
       end
-    end
-
-    def size_class
-      case size
-      when :sm
-        "text-xs px-1.5 py-0.5"
-      when :md
-        "text-sm px-2 py-0.5"
-      else
-        raise ArgumentError, "Invalid size: #{size}"
-      end
-    end
 
-    def color_class
-      case color
-      when :gray
-        "text-zinc-700 dark:text-zinc-200 bg-zinc-400/15 dark:bg-zinc-400/40"
-      when :red
-        "text-red-900 dark:text-red-200 bg-red-300/50 dark:bg-red-400/40"
-      when :orange
-        "text-orange-700 dark:text-orange-200 bg-orange-400/20 dark:bg-orange-400/40"
-      when :amber
-        "text-amber-700 dark:text-amber-200 bg-amber-400/20 dark:bg-amber-400/40"
-      when :yellow
-        "text-yellow-900 dark:text-yellow-200 bg-yellow-400/40 dark:bg-yellow-400/40"
-      when :lime
-        "text-lime-700 dark:text-lime-200 bg-lime-400/20 dark:bg-lime-400/40"
-      when :green
-        "text-green-800 dark:text-green-200 bg-green-500/20 dark:bg-green-400/40"
-      when :emerald
-        "text-emerald-700 dark:text-emerald-200 bg-emerald-400/20 dark:bg-emerald-400/40"
-      when :teal
-        "text-teal-700 dark:text-teal-200 bg-teal-400/20 dark:bg-teal-400/40"
-      when :cyan
-        "text-cyan-700 dark:text-cyan-200 bg-cyan-400/20 dark:bg-cyan-400/40"
-      when :sky
-        "text-sky-700 dark:text-sky-200 bg-sky-400/20 dark:bg-sky-400/40"
-      when :blue
-        "text-blue-700 dark:text-blue-200 bg-blue-400/20 dark:bg-blue-400/40"
-      when :indigo
-        "text-indigo-700 dark:text-indigo-200 bg-indigo-400/20 dark:bg-indigo-400/40"
-      when :violet
-        "text-violet-700 dark:text-violet-200 bg-violet-400/20 dark:bg-violet-400/40"
-      when :purple
-        "text-purple-700 dark:text-purple-200 bg-purple-400/20 dark:bg-purple-400/40"
-      when :fuchsia
-        "text-fuchsia-700 dark:text-fuchsia-200 bg-fuchsia-400/20 dark:bg-fuchsia-400/40"
-      when :pink
-        "text-pink-700 dark:text-pink-200 bg-pink-400/20 dark:bg-pink-400/40"
-      when :rose
-        "text-rose-700 dark:text-rose-200 bg-rose-400/20 dark:bg-rose-400/40"
-      else
-        raise ArgumentError, "Unknown color `#{color}'"
+      span(**root_attributes) do
+        span(**slot_attributes(:label)) do
+          block ? text_or_block(nil, &block) : plain(text.to_s)
+        end
       end
     end
   end

data/app/components/nitro_kit/button.rb

@@ -2,7 +2,13 @@
 
 module NitroKit
   class Button < Component
-    VARIANTS = %i[default primary destructive ghost]
+    VARIANTS = %i[default primary destructive ghost].freeze
+    SIZES = %i[xs sm md lg xl].freeze
+    TYPES = %i[button submit reset].freeze
+    SUBMISSION_INDICATORS = %i[spinner].freeze
+    DEFAULT_TYPE = :button
+    UNSET_TYPE = Object.new.freeze
+    private_constant :UNSET_TYPE
 
     def initialize(
       text = nil,
@@ -10,137 +16,208 @@ module NitroKit
       variant: :default,
       size: :md,
       icon: nil,
-      icon_right: nil,
-      **attrs
+      icon_end: nil,
+      label: nil,
+      id: nil,
+      type: UNSET_TYPE,
+      name: nil,
+      value: nil,
+      form: nil,
+      target: nil,
+      rel: nil,
+      download: nil,
+      disabled: false,
+      loading: false,
+      submission_indicator: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
     )
+      if !href.nil? && (!href.is_a?(String) || href.empty?)
+        raise ArgumentError, "Button href must be nil or a non-blank String"
+      end
+      if href && !type.equal?(UNSET_TYPE)
+        raise ArgumentError, "Link Buttons do not accept type; type: applies to native button elements"
+      end
+      if href && [ name, value, form ].any? { |option| !option.nil? }
+        raise ArgumentError, "Link Buttons do not accept name, value, or form"
+      end
+      if !href && [ target, rel, download ].any? { |option| !option.nil? }
+        raise ArgumentError, "Button elements do not accept target, rel, or download"
+      end
+      if !label.nil? && (!label.is_a?(String) || label.strip.empty?)
+        raise ArgumentError, "Button label: must be a non-blank String"
+      end
+      if text.is_a?(String) && text.strip.empty?
+        raise ArgumentError, "Button text must be non-blank"
+      end
+
       @text = text
       @href = href
       @icon = icon
-      @icon_right = icon_right
-      @size = size
-      @variant = variant
+      @icon_end = icon_end
+      @label = label
+      @variant = validate_choice!(:variant, variant, VARIANTS)
+      @size = validate_choice!(:size, size, SIZES)
+      @type = validate_choice!(:type, resolved_type(type), TYPES)
+      @loading = validate_boolean!(:loading, loading)
+      @disabled = validate_boolean!(:disabled, disabled) || @loading
+      @aria = aria
+      @submission_feedback = submission_feedback(data)
+      @submission_indicator = if submission_indicator.nil?
+        nil
+      else
+        validate_choice!(:submission_indicator, submission_indicator, SUBMISSION_INDICATORS)
+      end
+      if @submission_indicator && (href || @type != :submit)
+        raise ArgumentError, "submission_indicator: applies only to native submit Buttons"
+      end
+      if @submission_indicator && @loading
+        raise ArgumentError, "submission_indicator: and loading: cannot be combined"
+      end
+
+      owned_aria = {
+        label: @label,
+        busy: @loading ? true : nil
+      }.compact
+
+      native_attributes = if href
+        {
+          id:,
+          href: @disabled ? nil : href,
+          target:,
+          rel:,
+          download:,
+          tabindex: @disabled ? -1 : nil,
+          aria: owned_aria
+        }.compact.tap do |attributes|
+          if @disabled
+            attributes[:href] = nil
+            attributes[:aria] = attributes[:aria].merge(disabled: true)
+          end
+          attributes.delete(:aria) if attributes[:aria].empty?
+        end
+      else
+        {
+          id:,
+          type: @type,
+          name:,
+          value:,
+          form:,
+          disabled: @disabled,
+          aria: owned_aria.presence,
+          data: submission_data
+        }.compact
+      end
 
       super(
-        attrs,
-        class: [
-          base_class,
-          variant_class,
-          size_class
-        ]
+        component: :button,
+        attributes: native_attributes,
+        html:,
+        aria:,
+        data:,
+        variant:,
+        size:,
+        desperately_need_a_class:
       )
     end
 
-    attr_reader(
-      :text,
-      :href,
-      :icon,
-      :icon_right,
-      :size,
-      :variant
-    )
+    attr_reader :text, :href, :icon, :icon_end, :label, :size, :variant
+
+    def loading? = @loading
 
     def view_template(&block)
-      if href
-        a(href:, **attrs) do
-          contents(&block)
-        end
-      else
-        button(type: :button, **attrs) do
-          contents(&block)
-        end
+      raise ArgumentError, "Button accepts text or a block, not both" if !text.nil? && block
+      unless !text.nil? || block || icon || icon_end
+        raise ArgumentError, "Button requires text, a block, or an icon"
+      end
+      # Only render time knows whether a block supplies the visible label.
+      if text.nil? && !block && !accessible_label?
+        raise ArgumentError, "Icon-only Button requires label:, aria: { label: }, or aria: { labelledby: }"
       end
+
+      tag = href ? :a : :button
+      public_send(tag, **root_attributes) { contents(&block) }
     end
 
     private
 
-    def contents(&block)
-      has_content = text.present? || block_given?
+    def resolved_type(type)
+      return DEFAULT_TYPE if type.equal?(UNSET_TYPE)
+
+      type.to_s.to_sym
+    end
+
+    def submission_data
+      return unless @submission_feedback || @submission_indicator
 
-      if !has_content
-        return render(Icon.new(icon))
+      {
+        controller: "nk--button",
+        action: [
+          "submit@document->nk--button#submit",
+          "turbo:submit-end@document->nk--button#reset",
+          "turbo:before-cache@document->nk--button#reset"
+        ].join(" ")
+      }
+    end
+
+    def submission_feedback(data)
+      data.each do |key, value|
+        next unless normalized_data_attribute(key) == "turbo-submits-with"
+        return if value == false || value.nil?
+        return value if value.is_a?(String) && !value.strip.empty?
+
+        raise ArgumentError, "data-turbo-submits-with must be a non-blank String"
       end
 
-      render(Icon.new(icon)) if icon
+      nil
+    end
 
-      if block_given?
-        yield
-      else
-        span { plain(text) }
+    def contents(&block)
+      icon_only = text.nil? && !block
+      submission_spinner if @submission_indicator == :spinner
+      spinner(icon_only:) if loading?
+      icon_slot(icon, :icon_start, icon_only:) if icon && !loading?
+
+      if block || !text.nil?
+        span(**slot_attributes(:label)) do
+          block ? yield : plain(text.to_s)
+        end
       end
 
-      render(Icon.new(icon_right)) if icon_right
+      icon_slot(icon_end, :icon_end, icon_only:) if icon_end
     end
 
-    def base_class
-      [
-        "inline-flex items-center cursor-pointer shrink-0 justify-center rounded-md border gap-2 font-medium select-none",
-        # Disabled
-        "disabled:opacity-70 disabled:pointer-events-none",
-        # Focus
-        "focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-offset-2 focus-visible:ring-ring ring-offset-background",
-        # Icon
-        "[&_svg]:pointer-events-none [&_svg]:shrink-0"
-      ]
+    def submission_spinner
+      span(**slot_attributes(:submission_spinner, attributes: { aria: { hidden: true } })) do
+        render(Icon.new(:"loader-circle", size: icon_size))
+      end
     end
 
-    def variant_class
-      case variant
-      when :default
-        [
-          "bg-background text-foreground border-border",
-          "hover:bg-zinc-50 dark:hover:bg-zinc-900"
-        ]
-      when :primary
-        [
-          "bg-primary text-primary-foreground border-primary",
-          "hover:bg-primary/90 dark:hover:bg-primary/90"
-        ]
-      when :destructive
-        [
-          "bg-destructive text-destructive-foreground border-destructive",
-          "hover:bg-destructive/90 dark:hover:bg-destructive/90",
-          "disabled:text-destructive-foreground/80"
-        ]
-      when :ghost
-        [
-          "bg-transparent text-foreground border-transparent",
-          "hover:bg-zinc-200/50 dark:hover:bg-zinc-900",
-          "disabled:text-muted-content"
-        ]
-      else
-        raise ArgumentError, "Unknown variant `#{variant}'"
+    def spinner(icon_only:)
+      span(**slot_attributes(:spinner, attributes: { aria: { hidden: true } })) do
+        render(Icon.new(:"loader-circle", size: icon_only ? :md : icon_size))
       end
     end
 
-    def size_class
-      case size
-      when :xs
-        "px-1.5 h-6 text-xs [&_svg]:size-3"
-      when :sm
-        [
-          "px-2.5 h-7 text-sm [&_svg]:size-4",
-          "[&_svg:first-child:last-child]:-mx-1"
-        ]
-      when :md
-        [
-          "px-4 h-10 text-base [&_svg]:size-4",
-          # If icon only, make square
-          "[&_svg:first-child:last-child]:-mx-1"
-        ]
-      when :lg
-        [
-          "px-5 h-11 text-lg [&_svg]:size-5",
-          # If icon only, make square
-          "[&_svg:first-child:last-child]:-mx-2"
-        ]
-      when :xl
-        [
-          "px-8 h-14 text-2xl [&_svg]:size-5 gap-x-4",
-          # If icon only, make square
-          "[&_svg:first-child:last-child]:-mx-8"
-        ]
-      else
-        raise ArgumentError, "Unknown size `#{size}'"
+    def icon_slot(name, slot, icon_only:)
+      span(**slot_attributes(slot)) do
+        render(Icon.new(name, size: icon_only ? :md : icon_size))
+      end
+    end
+
+    def icon_size
+      { xs: :xs, sm: :sm, md: :sm, lg: :md, xl: :md }.fetch(size)
+    end
+
+    def accessible_label?
+      return true if @label
+
+      %w[label labelledby].any? do |name|
+        key = @aria.keys.find { |candidate| candidate.to_s.downcase.delete("_-") == name }
+        value = key && @aria[key]
+        value.is_a?(String) && !value.strip.empty?
       end
     end
   end