nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/accordion.rb

@@ -2,101 +2,161 @@
 
 module NitroKit
   class Accordion < Component
-    def initialize(**attrs)
+    MODES = %i[multiple single].freeze
+    Item = ::Data.define(:key, :title, :expanded, :content)
+
+    def initialize(
+      id:,
+      mode: :multiple,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @identifier = component_id(id)
+      @mode = validate_choice!(:mode, mode, MODES)
+      @items = []
+
       super(
-        attrs,
-        class: item_class,
-        data: { controller: "nk--accordion" }
+        component: :accordion,
+        attributes: {
+          id: @identifier,
+          data: { mode: @mode }
+        },
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
       )
     end
 
-    def view_template
-      div(**attrs) do
-        yield
+    attr_reader :identifier, :mode
+
+    def view_template(&block)
+      collect_items(&block)
+
+      div(**root_attributes) do
+        @items.each { |item| render_item(item) }
       end
     end
 
-    def item(**attrs)
-      builder do
-        div(**attrs) do
-          yield
-        end
+    def item(key, title:, expanded: false, &content)
+      ensure_collecting!
+
+      key = normalize_identity(key, name: "accordion item key")
+      title = validate_title!(title)
+      expanded = validate_boolean!(:expanded, expanded)
+      raise ArgumentError, "Accordion item #{key.inspect} requires content" unless content
+      raise ArgumentError, "Duplicate accordion item key #{key.inspect}" if @items.any? { |item| item.key == key }
+
+      if mode == :single && expanded && @items.any?(&:expanded)
+        raise ArgumentError, "Single accordion mode accepts only one expanded item"
       end
+
+      @items << Item.new(key:, title:, expanded:, content:)
+      nil
     end
 
-    def trigger(text = nil, **attrs)
-      builder do
-        button(
-          **mattr(
-            attrs,
-            type: "button",
-            class: trigger_class,
-            data: {
-              action: "nk--accordion#toggle",
-              nk__accordion_target: "trigger"
-            },
-            aria: { expanded: "false" }
+    private
+
+    def collect_items
+      raise ArgumentError, "Accordion requires an item declaration block" unless block_given?
+
+      @collecting = true
+      yield(self)
+      raise ArgumentError, "Accordion requires at least one item" if @items.empty?
+    ensure
+      @collecting = false
+    end
+
+    def render_item(item)
+      details(
+        **slot_attributes(
+          :item,
+          attributes: {
+            name: mode == :single ? identifier : nil,
+            open: item.expanded,
+            data: { key: item.key }
+          }
+        )
+      ) do
+        summary(
+          **slot_attributes(
+            :trigger,
+            attributes: {
+              id: trigger_id(item)
+            }
           )
         ) do
-          block_given? ? yield : plain(text)
-          chevron_icon
+          span(**slot_attributes(:label)) { item.title }
+          chevron
         end
-      end
-    end
 
-    def content(**attrs)
-      builder do
         div(
-          **mattr(
-            attrs,
-            class: content_class,
-            data: {
-              nk__accordion_target: "content"
-            },
-            aria: { hidden: "true" }
+          **slot_attributes(
+            :content,
+            attributes: {
+              id: content_id(item)
+            }
           )
         ) do
-          div(class: "pb-4") { yield }
+          render(item.content)
         end
       end
     end
 
-    private
+    def chevron
+      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 }
+          }
+        )
+      ) do |svg|
+        svg.path(d: "m4 6 4 4 4-4")
+      end
+    end
+
+    def trigger_id(item)
+      "#{identifier}-#{item.key}-trigger"
+    end
 
-    def item_class
-      "divide-y"
+    def content_id(item)
+      "#{identifier}-#{item.key}-content"
     end
 
-    def trigger_class
-      [
-        "flex w-full items-center justify-between py-4 font-medium cursor-pointer",
-        "group/accordion-trigger hover:underline transition-colors",
-        "[&[aria-expanded='true']>svg]:rotate-180",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
-      ]
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "Accordion items must be declared inside the render block"
     end
 
-    def content_class
-      [
-        "overflow-hidden transition-all duration-200",
-        "[&[aria-hidden='true']]:h-0 [&[aria-hidden='false']]:h-auto"
-      ]
+    def validate_title!(title)
+      return title if title.is_a?(String) && title.present?
+
+      raise ArgumentError, "Accordion item title must be a non-blank String"
     end
 
-    def arrow_class
-      "transition-transform duration-200 text-muted-content group-hover/accordion-trigger:text-primary"
+    def validate_boolean!(name, value)
+      return value if value == true || value == false
+
+      raise ArgumentError, "Accordion #{name} must be true or false"
     end
 
-    def chevron_icon
-      svg(
-        class: "transition-transform duration-200 size-4 self-center place-self-end mr-2 pointer-events-none text-muted-content group-hover/accordion-trigger:text-primary",
-        viewbox: "0 0 24 24",
-        fill: "none",
-        stroke: "currentColor",
-        stroke_width: 1
-      ) do |svg|
-        svg.path(d: "m6 9 6 6 6-6")
-      end
+    def component_id(value)
+      return value if value.is_a?(String) && value.present? && !value.match?(/\s/)
+
+      raise ArgumentError, "Accordion id must be a non-blank String without whitespace"
     end
   end
 end

data/app/components/nitro_kit/alert.rb

@@ -2,72 +2,109 @@
 
 module NitroKit
   class Alert < Component
-    VARIANTS = %i[default warning error success]
+    VARIANTS = %i[default info success warning error].freeze
 
-    def initialize(variant: :default, **attrs)
-      @variant = variant
+    # The palette family each semantic variant borrows in `palette.css`.
+    # Alert owns this mapping; it is not the Badge color axis.
+    VARIANT_PALETTE = {
+      default: :zinc,
+      info: :blue,
+      success: :green,
+      warning: :amber,
+      error: :red
+    }.freeze
+
+    LIVE_MODES = %i[off polite assertive].freeze
+
+    Child = ::Data.define(:component, :content)
+    private_constant :Child
+
+    def initialize(
+      variant: :default,
+      title: nil,
+      description: nil,
+      live: :off,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @variant = validate_choice!(:variant, variant, VARIANTS)
+      @live = validate_choice!(:live, live, LIVE_MODES)
+      @title_content = content_from_keyword(:title, title)
+      @description_content = content_from_keyword(:description, description)
+      @icon = nil
 
       super(
-        attrs,
-        role: "alert",
-        class: [ base_class, variant_class ]
+        component: :alert,
+        attributes: { id:, role: live_role },
+        html:,
+        aria:,
+        data:,
+        variant:,
+        desperately_need_a_class:
       )
     end
 
     attr_reader :variant
 
-    def view_template
-      div(**attrs) do
-        yield
-      end
-    end
+    def view_template(&block)
+      collect_declarations(&block)
 
-    def title(text = nil, **attrs, &block)
-      builder do
-        h5(**mattr(attrs, class: title_class)) do
-          text_or_block(text, &block)
+      div(**root_attributes) do
+        render_in_slot(@icon.component, :icon, &@icon.content) if @icon
+        if @title_content
+          div(**slot_attributes(:title)) { render_deferred_content(@title_content) }
+        end
+        if @description_content
+          div(**slot_attributes(:description)) { render_deferred_content(@description_content) }
         end
       end
     end
 
-    def description(text = nil, **attrs, &block)
-      builder do
-        div(**mattr(attrs, class: description_class)) do
-          text_or_block(text, &block)
-        end
+    def icon(component, &content)
+      ensure_collecting!
+      unless component.is_a?(NitroKit::Icon)
+        raise ArgumentError, "Alert icon must be a NitroKit::Icon"
       end
+      raise ArgumentError, "Alert accepts at most one icon" if @icon
+
+      @icon = Child.new(component:, content:)
+      nil
     end
 
-    private
+    def title(text = nil, &block)
+      ensure_collecting!
+      @title_content = declare_content(:title, @title_content, text, &block)
+      nil
+    end
 
-    def base_class
-      [
-        "relative border w-full rounded-md p-5 text-sm space-y-2",
-        "[&>svg~*]:pl-8 [&>svg]:absolute [&>svg]:top-5 [&>svg]:left-5"
-      ]
+    def description(text = nil, &block)
+      ensure_collecting!
+      @description_content = declare_content(:description, @description_content, text, &block)
+      nil
     end
 
-    def variant_class
-      case variant
-      when :default
-        "border-border bg-background text-foreground"
-      when :warning
-        "bg-yellow-300/20 dark:bg-yellow-300/20 text-yellow-900 dark:text-yellow-100 border-yellow-500/80 dark:border-yellow-400/50"
-      when :success
-        "bg-green-300/20 dark:bg-green-300/20 text-green-900 dark:text-green-100 border-green-500/80 dark:border-green-400/50"
-      when :error
-        "bg-red-300/20 dark:bg-red-300/20 text-red-900 dark:text-red-100 border-red-400/80 dark:border-red-400/50"
-      else
-        raise ArgumentError, "Invalid variant: #{variant}"
-      end
+    private
+
+    def collect_declarations
+      return unless block_given?
+
+      @collecting = true
+      yield(self)
+    ensure
+      @collecting = false
     end
 
-    def title_class
-      "font-medium text-lg leading-5"
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "Alert declarations must be inside the render block"
     end
 
-    def description_class
-      ""
+    def live_role
+      { off: nil, polite: "status", assertive: "alert" }.fetch(@live)
     end
   end
 end

data/app/components/nitro_kit/app_navigation.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class AppNavigation < Component
+    alias_method :html_header, :header
+    alias_method :html_footer, :footer
+
+    Item = ::Data.define(:text, :href, :icon, :badge, :current, :html, :aria, :data, :css_class)
+    Section = ::Data.define(:label, :entries)
+    Entry = ::Data.define(:kind)
+
+    def initialize(
+      label:,
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @label = validate_text!(:label, label)
+      @entries = []
+      @entry_target = nil
+      @phase = nil
+      @header = nil
+      @body = nil
+      @footer = nil
+      @spacer = false
+      @current_item = false
+      @item_count = 0
+
+      super(
+        component: :app_navigation,
+        attributes: { id:, aria: { label: @label } }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    attr_reader :label
+
+    def view_template(&declarations)
+      collect_structure(&declarations)
+      collect_body
+
+      nav(**root_attributes) do
+        render_header
+        render_body
+        render_footer
+      end
+    end
+
+    def header(&content)
+      ensure_phase!(:structure, :header)
+      raise ArgumentError, "AppNavigation accepts at most one header" if @header
+      raise ArgumentError, "AppNavigation header requires a block" unless content
+
+      @header = content
+      nil
+    end
+
+    def body(&content)
+      ensure_phase!(:structure, :body)
+      raise ArgumentError, "AppNavigation accepts exactly one body" if @body
+      raise ArgumentError, "AppNavigation body requires a block" unless content
+
+      @body = content
+      nil
+    end
+
+    def footer(&content)
+      ensure_phase!(:structure, :footer)
+      raise ArgumentError, "AppNavigation accepts at most one footer" if @footer
+      raise ArgumentError, "AppNavigation footer requires a block" unless content
+
+      @footer = content
+      nil
+    end
+
+    def section(label: nil, &content)
+      ensure_phase!(:body, :section)
+      raise ArgumentError, "AppNavigation section requires a block" unless content
+
+      entries = []
+      previous_entries = @entry_target
+      previous_phase = @phase
+
+      begin
+        @entry_target = entries
+        @phase = :section
+        output = capture(self, &content)
+        reject_rendered_output!(:section, output)
+        unless entries.any?(Item)
+          raise ArgumentError, "AppNavigation section requires at least one item"
+        end
+        previous_entries << Section.new(label: validate_optional_text!(:label, label), entries:)
+        nil
+      ensure
+        @entry_target = previous_entries
+        @phase = previous_phase
+      end
+    end
+
+    def item(
+      text,
+      href:,
+      icon: nil,
+      badge: nil,
+      badge_color: :neutral,
+      current: false,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      ensure_entry_phase!(:item)
+      text = validate_text!(:text, text)
+      href = validate_text!(:href, href)
+      icon = item_icon(icon)
+      badge = item_badge(badge, badge_color)
+      current = validate_boolean!(:current, current)
+
+      if current && @current_item
+        raise ArgumentError, "AppNavigation accepts at most one current item"
+      end
+
+      @current_item = true if current
+      @entry_target << Item.new(
+        text:,
+        href:,
+        icon:,
+        badge:,
+        current:,
+        html:,
+        aria:,
+        data:,
+        css_class: desperately_need_a_class
+      )
+      @item_count += 1
+      nil
+    end
+
+    def divider
+      ensure_entry_phase!(:divider)
+      @entry_target << Entry.new(kind: :divider)
+      nil
+    end
+
+    def spacer
+      ensure_phase!(:body, :spacer)
+      raise ArgumentError, "AppNavigation accepts at most one spacer" if @spacer
+
+      @spacer = true
+      @entry_target << Entry.new(kind: :spacer)
+      nil
+    end
+
+    private
+
+    def collect_structure
+      raise ArgumentError, "AppNavigation requires a declaration block" unless block_given?
+
+      @phase = :structure
+      output = capture(self) { |navigation| yield navigation }
+      reject_rendered_output!(:structure, output)
+      raise ArgumentError, "AppNavigation requires exactly one body" unless @body
+    ensure
+      @phase = nil
+    end
+
+    def collect_body
+      @phase = :body
+      @entry_target = @entries
+      @item_count = 0
+      output = capture(self, &@body)
+      reject_rendered_output!(:body, output)
+      raise ArgumentError, "AppNavigation body requires at least one item" if @item_count.zero?
+    ensure
+      @entry_target = nil
+      @phase = nil
+    end
+
+    def render_header
+      html_header(**slot_attributes(:header)) { render(@header) } if @header
+    end
+
+    def render_body
+      ul(**slot_attributes(:body)) do
+        @entries.each { |entry| render_entry(entry) }
+      end
+    end
+
+    def render_footer
+      html_footer(**slot_attributes(:footer)) { render(@footer) } if @footer
+    end
+
+    def render_entry(entry)
+      case entry
+      when Item then render_item(entry)
+      when Section then render_section(entry)
+      else entry.kind == :divider ? render_divider : render_spacer
+      end
+    end
+
+    def render_section(entry)
+      li(**slot_attributes(:section)) do
+        span(**slot_attributes(:section_label)) { plain(entry.label) } if entry.label
+        ul(**slot_attributes(:section_list, attributes: section_list_attributes(entry))) do
+          entry.entries.each { |child| render_entry(child) }
+        end
+      end
+    end
+
+    def section_list_attributes(entry)
+      entry.label ? { aria: { label: entry.label } } : {}
+    end
+
+    def render_item(entry)
+      li(**slot_attributes(:item)) do
+        a(
+          **slot_attributes(
+            :item_link,
+            attributes: {
+              href: entry.href,
+              aria: { current: entry.current ? "page" : nil },
+              data: { state: entry.current ? "current" : "default" }
+            },
+            html: entry.html,
+            aria: entry.aria,
+            data: entry.data,
+            desperately_need_a_class: entry.css_class
+          )
+        ) do
+          render_in_slot(entry.icon, :item_icon) if entry.icon
+          span(**slot_attributes(:item_label)) { plain(entry.text) }
+          render_in_slot(entry.badge, :item_badge) if entry.badge
+        end
+      end
+    end
+
+    def render_divider
+      li(**slot_attributes(:divider, aria: { hidden: true }))
+    end
+
+    def render_spacer
+      li(**slot_attributes(:spacer, aria: { hidden: true }))
+    end
+
+    def ensure_phase!(expected, declaration)
+      return if @phase == expected
+
+      location = expected == :structure ? "the render block" : "the body"
+      raise ArgumentError, "AppNavigation #{declaration} must be declared directly inside #{location}"
+    end
+
+    def ensure_entry_phase!(declaration)
+      return if %i[body section].include?(@phase)
+
+      raise ArgumentError, "AppNavigation #{declaration} must be declared inside the body or a section"
+    end
+
+    def reject_rendered_output!(location, output)
+      return if output.empty?
+
+      raise ArgumentError, "AppNavigation #{location} accepts declarations, not rendered content"
+    end
+
+    def validate_text!(name, value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, "#{name} must be a non-blank String"
+    end
+
+    def validate_optional_text!(name, value)
+      return if value.nil?
+
+      validate_text!(name, value)
+    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, "icon must be a non-blank String or Symbol"
+      end
+
+      Icon.new(value, size: :sm)
+    end
+
+    def item_badge(value, color)
+      if value.nil?
+        return if color == :neutral
+
+        raise ArgumentError, "badge_color requires a badge"
+      end
+
+      Badge.new(validate_badge_text!(value), size: :sm, color:)
+    end
+
+    def validate_badge_text!(value)
+      return value if value.is_a?(String) && !value.strip.empty?
+      return value.to_s if value.is_a?(Numeric)
+
+      raise ArgumentError, "badge must be a non-blank String or Numeric"
+    end
+  end
+end