nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/progressive_image.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class ProgressiveImage < Component
+    include Phlex::Rails::Helpers::Routes
+
+    SIZES = %i[sm md lg].freeze
+    PIXELS = { sm: 320, md: 720, lg: 1_440 }.freeze
+    PLACEHOLDER_PIXELS = 48
+
+    def initialize(
+      attachment:,
+      alt: nil,
+      size: :md,
+      decorative: false,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @attachment = validate_attachment!(attachment)
+      @size = validate_choice!(:size, size, SIZES)
+      @decorative = validate_boolean!(:decorative, decorative)
+      @attached = attachment&.attached? || false
+      @alt = validate_alt!(alt)
+
+      validate_attached_contract! if @attached
+
+      super(
+        component: :progressive_image,
+        attributes: {
+          id:,
+          aria: { busy: @attached ? true : nil },
+          data: {
+            state: @attached ? "loading" : "empty",
+            controller: @attached ? "nk--progressive-image" : nil
+          }.compact
+        },
+        html:,
+        aria:,
+        data:,
+        size:,
+        desperately_need_a_class:
+      )
+    end
+
+    attr_reader :attachment, :alt, :size, :decorative
+
+    def view_template
+      div(**root_attributes) do
+        if @attached
+          render_placeholder
+          render_image
+        end
+
+        render_fallback
+      end
+    end
+
+    private
+
+    def render_placeholder
+      img(
+        **slot_attributes(
+          :placeholder,
+          attributes: image_dimensions.merge(
+            src: variant_url(PLACEHOLDER_PIXELS),
+            alt: "",
+            loading: "eager",
+            decoding: "async"
+          ),
+          aria: { hidden: true }
+        )
+      )
+    end
+
+    def render_image
+      pixels = PIXELS.fetch(size)
+      image_url = variant_url(pixels)
+
+      img(
+        **slot_attributes(
+          :image,
+          attributes: image_dimensions.merge(
+            src: image_url,
+            srcset: "#{image_url} 1x, #{variant_url(pixels * 2)} 2x",
+            alt:,
+            loading: "lazy",
+            decoding: "async",
+            data: { nk__progressive_image_target: "image" }
+          )
+        )
+      )
+    end
+
+    def render_fallback
+      visible = !@attached
+      accessible = !decorative
+
+      span(
+        **slot_attributes(
+          :fallback,
+          attributes: {
+            hidden: visible ? nil : true,
+            # Only an attached image can change state after render, so only
+            # that fallback is a live region.
+            role: (accessible && @attached) ? "status" : nil
+          },
+          aria: {
+            hidden: accessible ? nil : true
+          },
+          data: @attached ? { nk__progressive_image_target: "fallback" } : {}
+        )
+      ) { fallback_text }
+    end
+
+    def fallback_text
+      alt.strip.empty? ? I18n.t("nitro_kit.progressive_image.unavailable") : alt
+    end
+
+    def variant_url(pixels)
+      representation = attachment.variant(resize_to_limit: [ pixels, pixels ])
+      return representation if representation.is_a?(String)
+
+      url_for(representation)
+    end
+
+    def image_dimensions
+      blob = attachment.blob
+      return {} if blob.respond_to?(:analyzed?) && !blob.analyzed?
+
+      metadata = blob.metadata
+      return {} unless metadata.is_a?(Hash)
+
+      width = metadata["width"] || metadata[:width]
+      height = metadata["height"] || metadata[:height]
+      return {} unless positive_dimension?(width) && positive_dimension?(height)
+
+      { width:, height: }
+    end
+
+    def positive_dimension?(value)
+      value.is_a?(Numeric) && value.positive?
+    end
+
+    def validate_attachment!(value)
+      return value if value.nil? || value.respond_to?(:attached?)
+
+      raise ArgumentError, "attachment must be nil or an Active Storage attachment"
+    end
+
+    def validate_attached_contract!
+      missing = %i[variant blob].reject { |method| attachment.respond_to?(method) }
+      unless missing.empty?
+        raise ArgumentError, "attached image must expose #{missing.join(' and ')}"
+      end
+
+      blob = attachment.blob
+      unless blob.respond_to?(:image?) && blob.image? && blob.respond_to?(:variable?) && blob.variable?
+        raise ArgumentError, "attached image must have an image blob that supports variants"
+      end
+    end
+
+    def validate_alt!(value)
+      unless value.nil? || value.is_a?(String)
+        raise ArgumentError, "alt must be a String or nil"
+      end
+      return "" if decorative
+
+      if value.nil?
+        raise ArgumentError, "alt: is required unless decorative: true"
+      end
+      if @attached && value.strip.empty?
+        raise ArgumentError, "attached non-decorative images require non-blank alt text"
+      end
+
+      value
+    end
+  end
+end

data/app/components/nitro_kit/radio_button.rb

@@ -2,34 +2,75 @@
 
 module NitroKit
   class RadioButton < Component
-    def initialize(label: nil, id: nil, wrapper: {}, size: :md, **attrs)
-      @label = label
-      @id = id || "nk--" + SecureRandom.hex(4)
-      @size = size
-      @wrapper = wrapper
+    SIZES = %i[md lg].freeze
+
+    def initialize(
+      label: nil,
+      description: nil,
+      id: nil,
+      name: nil,
+      value: "1",
+      checked: false,
+      disabled: false,
+      required: false,
+      invalid: false,
+      size: :md,
+      html: {},
+      aria: {},
+      data: {},
+      control_html: {},
+      control_aria: {},
+      control_data: {},
+      desperately_need_a_class: nil
+    )
+      @label = validate_optional_text!(:label, label)
+      @description = validate_optional_text!(:description, description)
+      @id = id
+      @name = name
+      @value = value
+      @checked = validate_boolean!(:checked, checked)
+      @disabled = validate_boolean!(:disabled, disabled)
+      @required = validate_boolean!(:required, required)
+      @invalid = validate_boolean!(:invalid, invalid)
+      @size = validate_choice!(:size, size, SIZES)
+      @control_html = control_html
+      @control_aria = control_aria
+      @control_data = control_data
+
+      if description && (!id.is_a?(String) || id.strip.empty?)
+        raise ArgumentError, "radio button requires a non-blank String id when description is present"
+      end
 
       super(
-        attrs,
-        id: @id,
-        type: "radio",
-        class: input_class
+        component: :radio_button,
+        size: @size,
+        attributes: {
+          data: { disabled: @disabled ? "true" : nil }.compact
+        },
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
       )
     end
 
-    alias :html_label :label
+    attr_reader :label, :description, :id, :name, :value, :size
 
-    attr_reader :id, :label, :size, :wrapper
+    def view_template(&block)
+      require_accessible_name!(&block)
 
-    def view_template
-      div(**mattr(wrapper, class: wrapper_class)) do
-        html_label(class: merge_class("inline-grid *:[grid-area:1/1] shrink-0 place-items-center", size_class)) do
-          input(**attrs)
-          dot
-        end
-
-        if label.present? || block_given?
-          render(Label.new(for: id)) do
-            label || (block_given? ? yield : nil)
+      div(**root_attributes) do
+        if label.nil? && !block
+          render_control
+          span(**slot_attributes(:indicator), aria: { hidden: "true" })
+        else
+          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
           end
         end
       end
@@ -37,41 +78,22 @@ module NitroKit
 
     private
 
-    def dot
-      svg(
-        class: merge_class(
-          "text-primary opacity-0 pointer-events-none",
-          "peer-checked:opacity-100"
+    def render_control
+      render_in_slot(
+        Input.new(
+          type: :radio,
+          id:,
+          name:,
+          value:,
+          checked: @checked,
+          disabled: @disabled,
+          required: @required,
+          html: @control_html,
+          aria: control_aria,
+          data: @control_data
         ),
-        viewbox: "0 0 20 20",
-        fill: "currentColor",
-        stroke: "none"
-      ) do |svg|
-        svg.circle(cx: 10, cy: 10, r: 10)
-      end
-    end
-
-    def wrapper_class
-      "inline-flex items-center gap-2"
-    end
-
-    def input_class
-      [
-        "peer appearance-none shadow-sm rounded-full border text-foreground bg-background",
-        "[&[aria-checked='true']]:bg-primary",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-      ]
-    end
-
-    def size_class
-      case size
-      when :md
-        "[&>input]:size-5 [&>svg]:size-2.5"
-      when :lg
-        "[&>input]:size-7 [&>svg]:size-3.5"
-      else
-        raise ArgumentError, "Unknown size `#{size}'"
-      end
+        :control
+      )
     end
   end
 end

data/app/components/nitro_kit/radio_button_group.rb

@@ -2,56 +2,127 @@
 
 module NitroKit
   class RadioButtonGroup < Component
-    def initialize(options_arg = nil, options: [], name: nil, value: nil, **attrs)
-      @options = options_arg || options
+    ORIENTATIONS = %i[vertical horizontal].freeze
+    PRESENTATIONS = %i[list cards segmented].freeze
 
-      @name = name
-      @group_value = value
+    alias :html_legend :legend
+
+    def initialize(
+      legend:,
+      options:,
+      name:,
+      value: nil,
+      id: nil,
+      description: nil,
+      orientation: :vertical,
+      presentation: :list,
+      disabled: false,
+      required: false,
+      size: :md,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @legend = validate_text!(:legend, legend)
+      @options = Array(options).map { |choice| Choice.coerce(choice) }.freeze
+      @name = validate_text!(:name, name)
+      @value = value
+      @id = id || deterministic_id(name)
+      @description = validate_optional_text!(:description, description)
+      @orientation = validate_choice!(:orientation, orientation, ORIENTATIONS)
+      @presentation = validate_choice!(:presentation, presentation, PRESENTATIONS)
+      @disabled = validate_boolean!(:disabled, disabled)
+      @required = validate_boolean!(:required, required)
+      @size = validate_choice!(:size, size, RadioButton::SIZES)
+
+      raise ArgumentError, "options cannot be empty" if @options.empty?
+      validate_unique_choices!
 
       super(
-        attrs,
-        name: @name,
-        class: "flex items-start flex-col gap-2"
+        component: :radio_button_group,
+        size: @size,
+        attributes: {
+          id: @id,
+          disabled: @disabled,
+          data: {
+            orientation: @orientation,
+            presentation: @presentation,
+            required: @required ? "true" : nil
+          }.compact
+        }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
       )
     end
 
-    attr_reader :name, :group_value, :options
+    attr_reader :legend, :options, :name, :value, :description, :id, :size, :orientation, :presentation
 
     def view_template
-      div(**attrs) do
-        if block_given?
-          yield
-        else
-          options.map { |o| item(*o) }
+      fieldset(**root_attributes) do
+        html_legend(**slot_attributes(:legend)) { plain(legend) }
+        if description
+          p(**slot_attributes(:description, attributes: { id: description_id }.compact)) do
+            plain(description.to_s)
+          end
         end
-      end
-    end
 
-    def title(text = nil, **attrs, &block)
-      builder do
-        render(Label.new(**attrs)) do
-          text_or_block(text, &block)
+        div(**slot_attributes(:choices)) do
+          options.each_with_index { |choice, index| render_choice(choice, index) }
         end
       end
     end
 
-    def item(text = nil, value_as_arg = nil, value: nil, **attrs, &block)
-      builder do
-        value ||= value_as_arg
-
-        render(
-          RadioButton.new(
-            **mattr(
-              attrs,
-              name: attrs.fetch(:name, name),
-              value:,
-              checked: group_value.presence == value
-            )
-          )
-        ) do
-          text_or_block(text, &block)
-        end
-      end
+    private
+
+    # The fieldset and its legend already scope the group description, so a
+    # choice never repeats it through aria-describedby.
+    def render_choice(choice, index)
+      render_in_slot(
+        RadioButton.new(
+          label: choice.label,
+          description: choice.description,
+          id: choice.id || choice_id(index),
+          name:,
+          value: choice.value,
+          checked: selected?(choice),
+          disabled: @disabled || choice.disabled,
+          required: @required,
+          size:
+        ),
+        :choice
+      )
+    end
+
+    def selected?(choice)
+      !value.nil? && value.to_s == choice.value.to_s
+    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/responsive_value.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class ResponsiveValue
+    BREAKPOINTS = {
+      "sm" => "40rem",
+      "md" => "48rem",
+      "lg" => "64rem",
+      "xl" => "80rem",
+      "2xl" => "96rem"
+    }.freeze
+
+    def initialize(property:, value:, allowed:)
+      @property = property
+      @allowed = allowed.map { |candidate| normalize(candidate) }.freeze
+      @values = parse(value).freeze
+      freeze
+    end
+
+    def to_s
+      [ nil, *BREAKPOINTS.keys ].filter_map do |breakpoint|
+        value = @values[breakpoint]
+        next unless value
+
+        breakpoint ? "#{breakpoint}:#{value}" : value
+      end.join(" ")
+    end
+
+    private
+
+    def parse(value)
+      tokens = tokens_from(value)
+      values = {}
+
+      tokens.each do |token|
+        breakpoint, candidate = split(token)
+        validate_breakpoint!(breakpoint) if breakpoint
+        validate_value!(candidate)
+
+        if values.key?(breakpoint)
+          label = breakpoint ? "breakpoint #{breakpoint.inspect}" : "base value"
+          raise ArgumentError, "Duplicate #{@property} #{label}"
+        end
+
+        values[breakpoint] = candidate
+      end
+
+      unless values.key?(nil)
+        raise ArgumentError, "#{@property} must include an unprefixed base value"
+      end
+
+      values
+    end
+
+    def tokens_from(value)
+      tokens = case value
+      when String
+        value.split
+      when Integer, Symbol
+        [ normalize(value) ]
+      else
+        raise ArgumentError,
+          "#{@property} must be an Integer, Symbol, or String; received #{value.inspect}"
+      end
+
+      raise ArgumentError, "#{@property} cannot be blank" if tokens.empty?
+
+      tokens
+    end
+
+    def normalize(value)
+      value.to_s.tr("_", "-")
+    end
+
+    def split(token)
+      breakpoint, separator, value = token.partition(":")
+      separator.empty? ? [ nil, breakpoint ] : [ breakpoint, value ]
+    end
+
+    def validate_breakpoint!(breakpoint)
+      return if BREAKPOINTS.key?(breakpoint)
+
+      raise ArgumentError,
+        "Unknown #{@property} breakpoint #{breakpoint.inspect}; expected one of: #{BREAKPOINTS.keys.join(", ")}"
+    end
+
+    def validate_value!(value)
+      return if @allowed.include?(value)
+
+      raise ArgumentError,
+        "Unknown #{@property} value #{value.inspect}; expected one of: #{@allowed.join(", ")}"
+    end
+  end
+end

data/app/components/nitro_kit/rich_text_area.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class RichTextArea < Component
+    def initialize(content, id: nil, data: {}, aria: {}, html: {}, desperately_need_a_class: nil)
+      @content = validate_content!(content)
+
+      super(component: :rich_text_area, attributes: { id: }.compact, data:, aria:, html:, desperately_need_a_class:)
+    end
+
+    attr_reader :content
+
+    def view_template
+      div(**root_attributes) do
+        div(**slot_attributes(:editor)) { raw(content) }
+      end
+    end
+
+    private
+
+    # The host application's rich-text helper owns the editor markup. Nitro
+    # only wraps it, so it must already be trusted output rather than a String
+    # this component would have to escape or mark safe on the caller's behalf.
+    def validate_content!(content)
+      raise ArgumentError, "content is required" if content.nil?
+      return content if content.is_a?(ActiveSupport::SafeBuffer) && content.html_safe?
+
+      raise ArgumentError, "RichTextArea content must be an ActiveSupport::SafeBuffer"
+    end
+  end
+end