nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.3

data/app/components/nitro_kit/sheet.rb

@@ -5,10 +5,10 @@ module NitroKit
     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)
+    Trigger = Data.define(:text, :variant, :size, :icon, :icon_end, :label, :disabled, :html, :aria, :data, :css_class, :content)
     private_constant :Trigger
 
-    Panel = Data.define(:title, :description, :content)
+    Panel = Data.define(:title, :description, :html, :aria, :data, :css_class, :content)
     private_constant :Panel
 
     def initialize(
@@ -39,6 +39,10 @@ module NitroKit
           id:,
           data: {
             controller: "nk--dialog",
+            action: [
+              "click->nk--dialog#invoke",
+              "turbo:before-cache@document->nk--dialog#closeForCache"
+            ].join(" "),
             side: @side,
             nk__dialog_dismissible_value: true
           }
@@ -73,6 +77,7 @@ module NitroKit
       html: {},
       aria: {},
       data: {},
+      desperately_need_a_class: nil,
       &content
     )
       ensure_collecting!
@@ -89,12 +94,21 @@ module NitroKit
         html:,
         aria:,
         data:,
+        css_class: desperately_need_a_class,
         content:
       )
       nil
     end
 
-    def panel(title:, description: nil, &content)
+    def panel(
+      title:,
+      description: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil,
+      &content
+    )
       ensure_collecting!
       raise ArgumentError, "Sheet accepts exactly one panel" if @panel
       unless title.is_a?(String) && title.present?
@@ -104,7 +118,7 @@ module NitroKit
         raise ArgumentError, "Sheet description: must be nil or a non-blank String"
       end
 
-      @panel = Panel.new(title:, description:, content:)
+      @panel = Panel.new(title:, description:, html:, aria:, data:, css_class: desperately_need_a_class, content:)
       nil
     end
 
@@ -130,9 +144,10 @@ module NitroKit
         icon_end: @trigger.icon_end,
         label: @trigger.label,
         disabled: @trigger.disabled,
-        html: command_attributes(@trigger.html, "show-modal", disabled: @trigger.disabled),
+        html: command_attributes(@trigger.html, "show-modal", commandfor: panel_id, disabled: @trigger.disabled),
         aria: @trigger.aria.merge(haspopup: "dialog"),
-        data: @trigger.data
+        data: command_data(@trigger.data, "show-modal", disabled: @trigger.disabled),
+        desperately_need_a_class: @trigger.css_class
       )
 
       render_in_slot(button, :trigger, &@trigger.content)
@@ -151,9 +166,13 @@ module NitroKit
             }.compact,
             data: {
               nk__dialog_target: "panel",
-              action: "click->nk--dialog#dismiss cancel->nk--dialog#cancel"
+              action: "click->nk--dialog#dismiss cancel->nk--dialog#cancel close->nk--dialog#restoreFocus"
             }
-          }
+          },
+          html: @panel.html,
+          aria: @panel.aria,
+          data: @panel.data,
+          desperately_need_a_class: @panel.css_class
         )
       ) do
         render_close
@@ -172,23 +191,13 @@ module NitroKit
           label: @close_label,
           variant: :ghost,
           size: :sm,
-          html: command_attributes({}, "close")
+          html: command_attributes({}, "close", commandfor: panel_id),
+          data: command_data({}, "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"

data/app/components/nitro_kit/stat_grid.rb

@@ -27,8 +27,8 @@ module NitroKit
       )
     end
 
-    def view_template
-      yield self if block_given?
+    def view_template(&block)
+      collect_declarations(&block)
       raise ArgumentError, "StatGrid requires at least one stat" if @stats.empty?
 
       div(**root_attributes) do
@@ -41,6 +41,7 @@ module NitroKit
     end
 
     def stat(key:, label:, value:, detail: nil)
+      ensure_collecting!
       key = normalize_identity(key, name: "stat key")
       raise ArgumentError, "StatGrid stat keys must be unique: #{key.inspect}" if @stats.any? { |stat| stat.key == key }
 
@@ -57,6 +58,21 @@ module NitroKit
 
     private
 
+    def collect_declarations
+      return unless block_given?
+
+      @collecting = true
+      yield(self)
+    ensure
+      @collecting = false
+    end
+
+    def ensure_collecting!
+      return if @collecting
+
+      raise ArgumentError, "StatGrid stats must be declared inside the render block"
+    end
+
     def render_stat(stat)
       div(**slot_attributes(:stat, attributes: { data: { key: stat.key } })) do
         dt(**slot_attributes(:label)) { plain(stat.label) }

data/app/components/nitro_kit/table.rb

@@ -28,6 +28,9 @@ module NitroKit
       desperately_need_a_class: nil
     )
       @sort = sort.nil? ? nil : normalize_sort_key(sort, name: "sort")
+      unless direction.nil? || direction.is_a?(Symbol) || direction.is_a?(String)
+        raise ArgumentError, "Table direction must be a Symbol or String"
+      end
       @direction = direction.nil? ? nil : validate_choice!(:direction, direction.to_sym, DIRECTIONS)
       unless @sort.nil? == @direction.nil?
         raise ArgumentError, "Table sort: and direction: must both be set or both be nil"
@@ -49,6 +52,7 @@ module NitroKit
         data: table_data
       )
       @caption = nil
+      @caption_id = "#{id || "nk-table-#{SecureRandom.hex(4)}"}-caption"
       @head = nil
       @bodies = []
       @sort_keys = []
@@ -61,7 +65,7 @@ module NitroKit
       yield self if block_given?
       @collecting_sections = false
 
-      div(**root_attributes) do
+      div(**scroll_region_attributes) do
         table(**@table_attributes) do
           render_caption if @caption
           render_section(:head, @head, :html_thead) if @head
@@ -141,6 +145,7 @@ module NitroKit
       ensure_rendering_row!(:th)
       raise ArgumentError, "Table th accepts text or a block, not both" if !text.nil? && block
       raise ArgumentError, "Table th href: requires sort:" if sort.nil? && !href.nil?
+      raise ArgumentError, "Table th sort: must be declared inside thead" if !sort.nil? && @rendering_section != :head
       alignment = validate_choice!(:align, align, ALIGNMENTS)
       scope = validate_choice!(:scope, scope, SCOPES)
       key = sort.nil? ? nil : declare_sort_header!(sort, href:)
@@ -235,10 +240,24 @@ module NitroKit
       raise ArgumentError, "Table #{name} must be a Symbol or non-blank String"
     end
 
+    # The wrapper scrolls horizontally, so keyboard users need it focusable and
+    # named. The caption is the only Nitro-owned name source, so the region is
+    # only exposed when one exists.
+    def scroll_region_attributes
+      return root_attributes unless @caption
+
+      root_attributes.merge(
+        tabindex: "0",
+        role: "region",
+        aria: root_attributes.fetch(:aria, {}).merge(labelledby: @caption_id)
+      )
+    end
+
     def render_caption
       html_caption(
         **slot_attributes(
           :caption,
+          attributes: { id: @caption_id },
           html: @caption.html,
           aria: @caption.aria,
           data: @caption.data,
@@ -258,10 +277,10 @@ module NitroKit
           desperately_need_a_class: section.css_class
         )
       ) do
-        @rendering_section = true
+        @rendering_section = slot
         render(section.content)
       ensure
-        @rendering_section = false
+        @rendering_section = nil
       end
     end
 

data/app/components/nitro_kit/tabs.rb

@@ -17,7 +17,7 @@ module NitroKit
       data: {},
       desperately_need_a_class: nil
     )
-      @identifier = component_id(id)
+      @identifier = validate_id!("Tabs id", id)
       @default = default.nil? ? nil : normalize_identity(default, name: "default tab key")
       @label = validate_label!(label)
       @orientation = validate_choice!(:orientation, orientation, ORIENTATIONS)
@@ -193,17 +193,5 @@ module NitroKit
 
       raise ArgumentError, "Tabs labels must be non-blank Strings"
     end
-
-    def validate_boolean!(name, value)
-      return value if value == true || value == false
-
-      raise ArgumentError, "Tabs #{name} must be true or false"
-    end
-
-    def component_id(value)
-      return value if value.is_a?(String) && value.present? && !value.match?(/\s/)
-
-      raise ArgumentError, "Tabs id must be a non-blank String without whitespace"
-    end
   end
 end

data/app/components/nitro_kit/toast.rb

@@ -32,6 +32,7 @@ module NitroKit
           attributes: {
             id:,
             role: ASSERTIVE_VARIANTS.include?(@variant) ? "alert" : "status",
+            aria: { atomic: true },
             data: {
               state: "open",
               turbo_temporary: true,
@@ -47,7 +48,7 @@ module NitroKit
             }
           },
           html:,
-          aria: aria.merge(atomic: true),
+          aria:,
           data:,
           variant:,
           desperately_need_a_class:
@@ -175,6 +176,7 @@ module NitroKit
         attributes: {
           id:,
           role: "region",
+          aria: { label: },
           data: {
             controller: "nk--toast",
             action: "turbo:before-cache@document->nk--toast#teardown",
@@ -182,7 +184,7 @@ module NitroKit
           }
         },
         html:,
-        aria: aria.merge(label:, live: "polite"),
+        aria:,
         data:,
         desperately_need_a_class:
       )

data/app/components/nitro_kit/toolbar.rb

@@ -30,6 +30,7 @@ module NitroKit
 
     def leading(html: {}, aria: {}, data: {}, desperately_need_a_class: nil, &block)
       raise ArgumentError, "Toolbar accepts at most one leading region" if @leading_region
+      raise ArgumentError, "Toolbar leading region requires a block" unless block
       @leading_region = Region.new(
         content: block,
         html:,
@@ -42,6 +43,7 @@ module NitroKit
 
     def trailing(html: {}, aria: {}, data: {}, desperately_need_a_class: nil, &block)
       raise ArgumentError, "Toolbar accepts at most one trailing region" if @trailing_region
+      raise ArgumentError, "Toolbar trailing region requires a block" unless block
       @trailing_region = Region.new(
         content: block,
         html:,

data/app/components/nitro_kit/tooltip.rb

@@ -16,7 +16,6 @@ module NitroKit
       :icon,
       :icon_end,
       :label,
-      :disabled,
       :target,
       :rel,
       :download,
@@ -48,7 +47,7 @@ module NitroKit
             controller: "nk--tooltip",
             placement: @placement,
             dismissed: nil,
-            action: "pointerleave->nk--tooltip#resetIfUninterested focusout->nk--tooltip#resetIfUninterested"
+            action: "keydown.esc@document->nk--tooltip#dismiss pointerleave->nk--tooltip#resetIfUninterested focusout->nk--tooltip#resetIfUninterested"
           }
         },
         html:,
@@ -81,8 +80,8 @@ module NitroKit
       text = nil,
       as: Button,
       href: nil,
-      variant: :default,
-      size: :md,
+      variant: nil,
+      size: nil,
       icon: nil,
       icon_end: nil,
       label: nil,
@@ -106,7 +105,7 @@ module NitroKit
       if as == :custom && content&.arity != 1
         raise ArgumentError, "Tooltip custom trigger block must accept trigger attributes"
       end
-      if as != Button && [ href, icon, icon_end, label, target, rel, download ].any?
+      if as != Button && [ href, variant, size, icon, icon_end, label, target, rel, download ].any?
         raise ArgumentError, "Tooltip #{as.inspect} trigger does not accept Button options"
       end
 
@@ -114,12 +113,11 @@ module NitroKit
         as:,
         text:,
         href:,
-        variant:,
-        size:,
+        variant: variant || :default,
+        size: size || :md,
         icon:,
         icon_end:,
         label:,
-        disabled: false,
         target:,
         rel:,
         download:,
@@ -156,7 +154,6 @@ module NitroKit
         icon: @trigger.icon,
         icon_end: @trigger.icon_end,
         label: @trigger.label,
-        disabled: @trigger.disabled,
         target: @trigger.target,
         rel: @trigger.rel,
         download: @trigger.download,
@@ -192,7 +189,7 @@ module NitroKit
     end
 
     def render_custom_trigger
-      span(**slot_attributes(:trigger)) do
+      div(**slot_attributes(:trigger)) do
         raw(safe(capture(trigger_attributes, &@trigger.content)))
       end
     end

data/app/javascript/controllers/nk/app_shell_controller.js

@@ -1,6 +1,6 @@
 import { Controller } from "@hotwired/stimulus";
 
-const narrowViewport = "(max-width: 48rem)";
+const narrowViewport = "(width < 48rem)";
 
 export default class extends Controller {
   static targets = ["dialog", "navigation", "sidebar", "trigger"];
@@ -168,8 +168,8 @@ export default class extends Controller {
     const focusTarget = this.previouslyFocused?.isConnected
       ? this.previouslyFocused
       : this.hasTriggerTarget
-        ? this.triggerTarget
-        : null;
+      ? this.triggerTarget
+      : null;
 
     this.restoreNavigation();
     this.setState(false);

data/app/javascript/controllers/nk/appearance_controller.js

@@ -48,6 +48,12 @@ export default class extends Controller {
         input.checked = input.value === preference;
       } else if (input.localName === "select") {
         input.value = preference;
+      } else if (input.dataset.appearancePreference) {
+        input.setAttribute("role", "menuitemradio");
+        input.setAttribute(
+          "aria-checked",
+          input.dataset.appearancePreference === preference,
+        );
       }
     });
     this.updateTriggerGlyph(preference);

data/app/javascript/controllers/nk/combobox_controller.js

@@ -50,6 +50,7 @@ export default class extends Controller {
   }
 
   connect() {
+    this.outsidePointerDown = this.outsidePointerDown.bind(this);
     this.activeOption = null;
     this.enhanced = true;
     this.nativeRequired = this.requiredValue;
@@ -64,6 +65,7 @@ export default class extends Controller {
 
   disconnect() {
     this.stopPositioning?.();
+    this.stopOutsideDismissal();
     this.enhanced = false;
     const control = this.element.querySelector(
       ':scope > [data-slot="combobox-control"]',
@@ -143,6 +145,17 @@ export default class extends Controller {
   open() {
     if (this.inputTarget.disabled) return;
 
+    // A committed selection is replaced, not appended to: opening selects the
+    // visible text so the first keystroke starts a fresh filter.
+    if (!this.openValue && this.inputTarget.value !== "") {
+      this.inputTarget.select();
+      this.inputTarget.addEventListener(
+        "mouseup",
+        (event) => event.preventDefault(),
+        { once: true },
+      );
+    }
+
     this.openValue = true;
   }
 
@@ -151,10 +164,30 @@ export default class extends Controller {
     this.setActive(null);
   }
 
-  closeFromOutside(event) {
+  // Capture-phase document pointerdown mirrors the Dropdown controller: iOS
+  // Safari does not reliably deliver window click events for outside taps.
+  outsidePointerDown(event) {
     if (!this.element.contains(event.target)) this.close();
   }
 
+  startOutsideDismissal() {
+    if (this.stopOutsideDismissalListener) return;
+
+    document.addEventListener("pointerdown", this.outsidePointerDown, true);
+    this.stopOutsideDismissalListener = () => {
+      document.removeEventListener(
+        "pointerdown",
+        this.outsidePointerDown,
+        true,
+      );
+      this.stopOutsideDismissalListener = null;
+    };
+  }
+
+  stopOutsideDismissal() {
+    this.stopOutsideDismissalListener?.();
+  }
+
   filter() {
     const query = this.inputTarget.value.trim().toLocaleLowerCase();
     let exactMatch = null;
@@ -268,9 +301,11 @@ export default class extends Controller {
 
     if (open) {
       this.startPositioning();
+      this.startOutsideDismissal();
     } else {
       this.stopPositioning?.();
       this.stopPositioning = null;
+      this.stopOutsideDismissal();
     }
   }
 
@@ -351,6 +386,21 @@ export default class extends Controller {
 
     this.statusTarget.textContent =
       count === 0 ? this.noResultsMessage : this.resultsMessage(count);
+    this.toggleEmptyState(count === 0);
+  }
+
+  toggleEmptyState(empty) {
+    if (empty && !this.emptyElement) {
+      const item = document.createElement("li");
+      item.setAttribute("role", "presentation");
+      item.setAttribute("data-slot", "combobox-empty");
+      item.textContent = this.noResultsMessage;
+      this.listboxTarget.append(item);
+      this.emptyElement = item;
+    } else if (!empty && this.emptyElement) {
+      this.emptyElement.remove();
+      this.emptyElement = null;
+    }
   }
 
   get visibleOptions() {

data/app/javascript/controllers/nk/command_palette_controller.js

@@ -22,13 +22,13 @@ export default class extends Controller {
     this.connected = true;
     this.restoreFocus = true;
     this.loadedQuery = this.inputTarget.value;
-    this.triggerTarget.removeAttribute("command");
     this.searchTarget.hidden = false;
     this.element.dataset.enhanced = "true";
   }
 
   disconnect() {
     this.connected = false;
+    clearTimeout(this.openTimer);
     clearTimeout(this.searchTimer);
     const trigger = this.element.querySelector(
       ':scope > [data-slot="command-palette-trigger"]',
@@ -51,21 +51,21 @@ export default class extends Controller {
       });
     if (empty) empty.hidden = true;
     if (status) status.textContent = "";
-    trigger?.setAttribute("command", "show-modal");
     if (search) search.hidden = true;
     delete this.element.dataset.enhanced;
   }
 
-  open(event) {
-    event?.preventDefault();
-    if (!this.canOpen) return;
+  openedByTrigger(event) {
+    if (!this.canOpen) {
+      event.preventDefault();
+      event.stopPropagation();
+      return;
+    }
 
-    this.returnFocus = document.activeElement;
+    this.returnFocus = event.currentTarget;
     this.restoreFocus = true;
-    this.reset();
-    this.panelTarget.showModal();
-    this.inputTarget.focus();
-    if (this.hasFormTarget) this.submitSearch();
+    clearTimeout(this.openTimer);
+    this.openTimer = setTimeout(() => this.#prepareOpenPanel(), 0);
   }
 
   shortcut(event) {
@@ -87,7 +87,9 @@ export default class extends Controller {
       if (!this.canOpen) return;
 
       event.preventDefault();
-      this.open();
+      this.returnFocus = document.activeElement;
+      this.panelTarget.showModal();
+      this.#prepareOpenPanel();
     }
   }
 
@@ -246,4 +248,12 @@ export default class extends Controller {
 
     return !activeModal || activeModal.contains(this.element);
   }
+
+  #prepareOpenPanel() {
+    if (!this.panelTarget.open) return;
+
+    this.reset();
+    this.inputTarget.focus();
+    if (this.hasFormTarget) this.submitSearch();
+  }
 }

data/app/javascript/controllers/nk/dialog_controller.js

@@ -4,6 +4,43 @@ export default class extends Controller {
   static targets = ["panel"];
   static values = { dismissible: Boolean };
 
+  disconnect() {
+    this.returnFocus = null;
+  }
+
+  invoke(event) {
+    const invoker = event.target.closest(
+      "[command], [data-nk--dialog-command]",
+    );
+    if (!invoker || !this.element.contains(invoker) || invoker.disabled) return;
+
+    const command =
+      invoker.getAttribute("command") ||
+      invoker.getAttribute("data-nk--dialog-command");
+    if (!["show-modal", "close"].includes(command)) return;
+
+    const panel = this.#commandPanel(invoker);
+    if (!panel) return;
+    if (command === "show-modal") this.returnFocus = invoker;
+    if (this.#nativeRelationshipRuns(invoker, panel, command)) return;
+
+    event.preventDefault();
+    if (command === "show-modal" && !panel.open) panel.showModal();
+    if (command === "close" && panel.open) panel.close();
+  }
+
+  closeForCache() {
+    this.returnFocus = null;
+    if (this.panelTarget.open) this.panelTarget.close();
+  }
+
+  restoreFocus() {
+    const returnFocus = this.returnFocus;
+
+    this.returnFocus = null;
+    if (returnFocus?.isConnected) returnFocus.focus();
+  }
+
   dismiss(event) {
     if (!this.dismissibleValue || event.target !== this.panelTarget) return;
 
@@ -20,4 +57,21 @@ export default class extends Controller {
   cancel(event) {
     if (!this.dismissibleValue) event.preventDefault();
   }
+
+  #commandPanel(invoker) {
+    const targetId = invoker.getAttribute("commandfor");
+    if (targetId) {
+      const target = document.getElementById(targetId);
+      if (target instanceof HTMLDialogElement && this.element.contains(target))
+        return target;
+    }
+
+    return invoker.hasAttribute("data-nk--dialog-command")
+      ? this.panelTarget
+      : null;
+  }
+
+  #nativeRelationshipRuns(invoker, panel, command) {
+    return invoker.commandForElement === panel && invoker.command === command;
+  }
 }