nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/details_table.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class DetailsTable < Component
+    include Phlex::Rails::Helpers::Routes
+
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+    Field = Data.define(:attribute, :label, :value, :content)
+
+    def initialize(
+      record,
+      caption: nil,
+      label: nil,
+      empty_text: nil,
+      boolean_labels: nil,
+      route_base: nil,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @record = record
+      @route_base = route_base
+      @caption = caption.nil? ? nil : validate_text!("caption", caption)
+      @empty_text = validate_text!("empty_text", empty_text || I18n.t("nitro_kit.details_table.empty"))
+      @boolean_labels = validate_boolean_labels!(boolean_labels || default_boolean_labels)
+      @fields = []
+      @table = Table.new(
+        table_aria: label.nil? ? {} : { label: validate_text!("label", label) }
+      )
+
+      super(
+        component: :details_table,
+        attributes: { id: }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    attr_reader :record, :route_base
+
+    def view_template
+      yield self if block_given?
+      raise ArgumentError, "DetailsTable requires at least one field" if @fields.empty?
+
+      div(**root_attributes) do
+        render_in_slot(@table, :table) do
+          @table.caption(@caption) if @caption
+          @table.tbody do
+            @fields.each { |field| render_field(field) }
+          end
+        end
+      end
+    end
+
+    def fields(*attributes)
+      raise ArgumentError, "DetailsTable fields requires at least one attribute" if attributes.empty?
+
+      attributes.each { |attribute| field(attribute) }
+      nil
+    end
+
+    def field(attribute, label: nil, value: UNSET, &content)
+      attribute = validate_attribute!(attribute)
+      if @fields.any? { |field| field.attribute.to_s == attribute.to_s }
+        raise ArgumentError, "DetailsTable field keys must be unique: #{attribute.inspect}"
+      end
+      label = label.nil? ? attribute.to_s.humanize : validate_text!("field label", label)
+      resolved_value = value.equal?(UNSET) ? resolve_attribute(attribute) : value
+
+      @fields << Field.new(attribute:, label:, value: resolved_value, content:)
+      nil
+    end
+
+    private
+
+    def render_field(field)
+      @table.tr do
+        @table.th(field.label, scope: :row)
+        @table.td do
+          if field.content
+            field.content.call(field.value)
+          else
+            render_value(field.value)
+          end
+        end
+      end
+    end
+
+    def render_value(value)
+      case value
+      when nil
+        em(**slot_attributes(:empty)) { plain(@empty_text) }
+      when true, false
+        span(**slot_attributes(:boolean)) { plain(@boolean_labels.fetch(value)) }
+      when Date, Time, ActiveSupport::TimeWithZone
+        time(**slot_attributes(:time, attributes: { datetime: value.iso8601 })) do
+          plain(I18n.localize(value, format: :long).to_s)
+        end
+      when Numeric
+        span(**slot_attributes(:number)) { plain(value.to_s) }
+      when Symbol
+        plain(value.to_s.humanize)
+      when String
+        render_string(value)
+      else
+        render_special_value(value)
+      end
+    end
+
+    def render_string(value)
+      if value.start_with?("https://", "http://")
+        a(
+          **slot_attributes(
+            :link,
+            attributes: { href: value, target: "_blank", rel: "noopener noreferrer" }
+          )
+        ) { plain(value) }
+      else
+        plain(value)
+      end
+    end
+
+    def render_special_value(value)
+      if active_storage_attachment?(value)
+        render_attachment(value)
+      elsif active_record?(value)
+        render_record(value)
+      elsif collection?(value)
+        render_collection(value)
+      else
+        plain(value.to_s)
+      end
+    end
+
+    def render_attachment(attachment)
+      return render_value(nil) unless attachment.attached?
+
+      if attachment.blob.image? && attachment.blob.variable?
+        render_in_slot(
+          ProgressiveImage.new(
+            attachment:,
+            alt: attachment.filename.to_s,
+            size: :sm
+          ),
+          :attachment
+        )
+      else
+        code(**slot_attributes(:file)) { plain(attachment.filename.to_s) }
+      end
+    end
+
+    def render_record(value)
+      route = route_base ? [ *Array(route_base), value ] : value
+      a(**slot_attributes(:record, attributes: { href: url_for(route) })) do
+        plain(record_name(value))
+      end
+    end
+
+    def render_collection(values)
+      span(**slot_attributes(:list)) do
+        values.each_with_index do |value, index|
+          plain(", ") if index.positive?
+          span(**slot_attributes(:list_item)) { render_value(value) }
+        end
+      end
+    end
+
+    def record_name(value)
+      label = value.to_label if value.respond_to?(:to_label)
+      label = value.name if label.blank? && value.respond_to?(:name)
+      label.presence || "#{value.class.model_name.human} ##{value.id}"
+    end
+
+    def active_storage_attachment?(value)
+      defined?(ActiveStorage::Attached::One) && value.is_a?(ActiveStorage::Attached::One)
+    end
+
+    def active_record?(value)
+      defined?(ActiveRecord::Base) && value.is_a?(ActiveRecord::Base)
+    end
+
+    def collection?(value)
+      value.is_a?(Array) || (
+        defined?(ActiveRecord::Associations::CollectionProxy) &&
+          value.is_a?(ActiveRecord::Associations::CollectionProxy)
+      )
+    end
+
+    def resolve_attribute(attribute)
+      return record.public_send(attribute) if record.respond_to?(attribute)
+
+      raise ArgumentError, "#{record.class} does not expose #{attribute.inspect}"
+    end
+
+    def validate_attribute!(attribute)
+      return attribute if attribute.is_a?(Symbol)
+      return attribute if attribute.is_a?(String) && !attribute.strip.empty?
+
+      raise ArgumentError, "DetailsTable field attribute must be a Symbol or non-blank String"
+    end
+
+    def validate_text!(name, value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, "DetailsTable #{name} must be a non-blank String"
+    end
+
+    def default_boolean_labels
+      {
+        true => I18n.t("nitro_kit.details_table.boolean_true"),
+        false => I18n.t("nitro_kit.details_table.boolean_false")
+      }
+    end
+
+    def validate_boolean_labels!(labels)
+      unless labels.is_a?(Hash) && labels.keys.sort_by(&:to_s) == [ false, true ]
+        raise ArgumentError, "DetailsTable boolean_labels must be a Hash with true and false keys"
+      end
+
+      labels.each { |key, value| validate_text!("boolean_labels[#{key}]", value) }
+      labels
+    end
+  end
+end

data/app/components/nitro_kit/dialog.rb

@@ -2,117 +2,291 @@
 
 module NitroKit
   class Dialog < Component
-    def initialize(identifier: nil, **attrs)
-      @identifier = identifier || SecureRandom.hex(6)
+    Trigger = ::Data.define(:text, :variant, :size, :disabled, :html, :aria, :data, :css_class, :content)
+    private_constant :Trigger
+
+    Panel = ::Data.define(:title, :description, :nonmodal, :html, :aria, :data, :css_class, :content)
+    private_constant :Panel
+
+    CloseButton = ::Data.define(:label, :html, :aria, :data, :css_class)
+    private_constant :CloseButton
+
+    def initialize(
+      id:,
+      dismissible: true,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      unless id.is_a?(String) && id.present? && !id.match?(/\s/)
+        raise ArgumentError, "Dialog id: must be a non-blank String without whitespace"
+      end
+
+      @id = id
+      @dismissible = validate_boolean!(:dismissible, dismissible)
 
       super(
-        attrs,
-        data: { controller: "nk--dialog", action: "click->nk--dialog#clickOutside" }
+        component: :dialog,
+        attributes: {
+          id:,
+          data: {
+            controller: "nk--dialog",
+            nk__dialog_dismissible_value: @dismissible
+          }
+        },
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
       )
     end
 
-    attr_reader :identifier
+    attr_reader :id
 
-    def view_template
-      div(**attrs) do
-        yield
+    def view_template(&block)
+      collect_declarations(&block)
+
+      div(**root_attributes) do
+        render_trigger if @trigger
+        render_panel
       end
     end
 
-    def trigger(text = nil, as: Button, **attrs, &block)
-      builder do
-        trigger_attrs = mattr(
-          attrs,
-          data: {
-            nk__dialog_target: "trigger",
-            action: "click->nk--dialog#open"
-          }
-        )
+    def trigger(
+      text = nil,
+      variant: :default,
+      size: :md,
+      disabled: false,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil,
+      &content
+    )
+      ensure_collecting!
+      raise ArgumentError, "Dialog accepts at most one trigger" if @trigger
 
-        case as
-        when Symbol
-          send(as, **trigger_attrs) do
-            text_or_block(text, &block)
-          end
-        else
-          render(as.new(**trigger_attrs)) do
-            text_or_block(text, &block)
-          end
-        end
-      end
+      @trigger = Trigger.new(
+        text:,
+        variant:,
+        size:,
+        disabled: validate_boolean!(:disabled, disabled),
+        html:,
+        aria:,
+        data:,
+        css_class: desperately_need_a_class,
+        content:
+      )
+      nil
     end
 
-    alias :html_dialog :dialog
+    def panel(
+      title:,
+      description: nil,
+      nonmodal: false,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil,
+      &content
+    )
+      ensure_collecting!
+      raise ArgumentError, "Dialog accepts exactly one panel" if @panel
 
-    def dialog(**attrs)
-      builder do
-        html_dialog(
-          **mattr(
-            attrs,
-            class: dialog_class,
-            data: { nk__dialog_target: "dialog" },
-            aria: {
-              labelledby: id(:title),
-              describedby: id(:description)
-            }
-          )
-        ) do
-          yield
-        end
+      unless title.is_a?(String) && title.present?
+        raise ArgumentError, "Dialog title: must be a non-blank String"
       end
+      unless description.nil? || (description.is_a?(String) && description.present?)
+        raise ArgumentError, "Dialog description: must be nil or a non-blank String"
+      end
+
+      @panel = Panel.new(
+        title:,
+        description:,
+        nonmodal: validate_boolean!(:nonmodal, nonmodal),
+        html:,
+        aria:,
+        data:,
+        css_class: desperately_need_a_class,
+        content:
+      )
+      nil
     end
 
-    def close_button(**attrs)
-      builder do
-        render(
-          Button.new(
-            **mattr(
-              attrs,
-              variant: :ghost,
-              size: :sm,
-              class: "absolute top-2 right-2",
-              data: { action: "nk--dialog#close" }
-            )
-          )
-        ) do
-          render(Icon.new(:x))
-        end
+    def close_button(
+      label: I18n.t("nitro_kit.dialog.close"),
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      ensure_rendering_panel!
+      raise ArgumentError, "Dialog accepts at most one close button" if @close_button
+      unless @dismissible
+        raise ArgumentError, "Dialog dismissible: false renders no close button"
       end
+
+      @close_button = CloseButton.new(
+        label:,
+        html:,
+        aria:,
+        data:,
+        css_class: desperately_need_a_class
+      )
+      nil
     end
 
-    def title(text = nil, **attrs, &block)
-      builder do
-        h2(**mattr(attrs, id: id(:title), class: "text-lg font-semibold mb-2")) do
-          text_or_block(text, &block)
-        end
+    private
+
+    def collect_declarations
+      raise ArgumentError, "Dialog requires a declaration block" unless block_given?
+
+      @collecting = true
+      yield(self)
+      raise ArgumentError, "Dialog requires exactly one panel" unless @panel
+
+      if @panel.nonmodal && @trigger
+        raise ArgumentError,
+          "Dialog nonmodal: true cannot be combined with a trigger; the trigger opens the panel modally"
       end
+    ensure
+      @collecting = false
     end
 
-    def description(text = nil, **attrs, &block)
-      builder do
-        div(
-          **mattr(
-            attrs,
-            id: id(:description),
-            class: "text-muted-content mb-6 text-sm leading-relaxed"
-          )
-        ) do
-          text_or_block(text, &block)
-        end
+    def render_trigger
+      component = Button.new(
+        @trigger.text,
+        variant: @trigger.variant,
+        size: @trigger.size,
+        disabled: @trigger.disabled,
+        html: with_command(@trigger.html, "show-modal", disabled: @trigger.disabled),
+        aria: @trigger.aria.merge(haspopup: "dialog"),
+        data: @trigger.data,
+        desperately_need_a_class: @trigger.css_class
+      )
+
+      if @trigger.content
+        render_in_slot(component, :trigger) { render(@trigger.content) }
+      else
+        render_in_slot(component, :trigger)
       end
     end
 
-    private
+    def render_panel
+      owned_aria = {
+        labelledby: element_id(:title),
+        describedby: @panel.description.nil? ? nil : element_id(:description)
+      }.compact
+
+      content = capture_panel_content
+
+      dialog(
+        **slot_attributes(
+          :panel,
+          attributes: {
+            id: element_id(:panel),
+            open: @panel.nonmodal,
+            closedby: @dismissible ? "any" : "none",
+            aria: owned_aria,
+            data: {
+              nk__dialog_target: "panel",
+              action: "click->nk--dialog#dismiss cancel->nk--dialog#cancel"
+            }
+          },
+          html: @panel.html,
+          aria: @panel.aria,
+          data: @panel.data,
+          desperately_need_a_class: @panel.css_class
+        )
+      ) do
+        render_close_button if @dismissible
+        render_title
+        render_description if @panel.description
+        raw(safe(content))
+      end
+    end
+
+    # The panel content is captured first so Nitro owns the rendered order:
+    # close button, title, description, then application content. A sticky
+    # close button must precede scrolling content in the DOM.
+    def capture_panel_content
+      return "" unless @panel.content
+
+      @rendering_panel = true
+      capture { render(@panel.content) }
+    ensure
+      @rendering_panel = false
+    end
+
+    def render_close_button
+      declaration = @close_button || CloseButton.new(
+        label: I18n.t("nitro_kit.dialog.close"),
+        html: {},
+        aria: {},
+        data: {},
+        css_class: nil
+      )
+
+      render_in_slot(
+        Button.new(
+          icon: :x,
+          variant: :ghost,
+          size: :sm,
+          html: with_command(declaration.html, "close"),
+          aria: declaration.aria.merge(label: declaration.label),
+          data: declaration.data,
+          desperately_need_a_class: declaration.css_class
+        ),
+        :close
+      )
+    end
+
+    def render_title
+      h2(
+        **slot_attributes(
+          :title,
+          attributes: { id: element_id(:title) }
+        )
+      ) { @panel.title }
+    end
+
+    def render_description
+      div(
+        **slot_attributes(
+          :description,
+          attributes: { id: element_id(:description) }
+        )
+      ) { @panel.description }
+    end
+
+    def element_id(suffix)
+      "#{id}-#{suffix}"
+    end
+
+    def ensure_collecting!
+      return if @collecting
 
-    def id(suffix = nil)
-      "nk-#{identifier}#{suffix ? "-#{suffix}" : ""}"
+      raise ArgumentError, "Dialog declarations must be inside the render block"
     end
 
-    def dialog_class
-      [
-        "border rounded-xl max-w-lg w-full bg-background text-foreground shadow-lg m-auto p-6",
-        "dark:backdrop:bg-black/50"
-      ]
+    def ensure_rendering_panel!
+      return if @rendering_panel
+
+      raise ArgumentError, "Dialog close button must be declared inside the panel block"
+    end
+
+    def with_command(html, command, disabled: false)
+      unless html.is_a?(Hash)
+        raise ArgumentError, "html must be a Hash"
+      end
+
+      collision = html.keys.find { |key| %w[command commandfor].include?(key.to_s.downcase) }
+      if collision
+        raise ArgumentError, "#{collision}: is owned by Dialog"
+      end
+
+      disabled ? html : html.merge(command:, commandfor: element_id(:panel))
     end
   end
 end