nitro_kit 0.9.0 → 2.0.0.alpha.2

data/app/components/nitro_kit/app_shell.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class AppShell < Component
+    alias_method :html_main, :main
+
+    LAYOUTS = %i[sidebar topbar hybrid].freeze
+    REGIONS = %i[brand navigation topbar main].freeze
+    REQUIRED_REGIONS = %i[navigation main].freeze
+    private_constant :REQUIRED_REGIONS
+
+    def initialize(
+      id:,
+      layout: :sidebar,
+      skip_link_label: I18n.t("nitro_kit.app_shell.skip_link"),
+      open_navigation_label: I18n.t("nitro_kit.app_shell.open_navigation"),
+      close_navigation_label: I18n.t("nitro_kit.app_shell.close_navigation"),
+      navigation_dialog_label: I18n.t("nitro_kit.app_shell.navigation_dialog"),
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @identifier = component_id(id)
+      @layout = validate_choice!(:layout, layout, LAYOUTS)
+      @skip_link_label = validate_label!(:skip_link_label, skip_link_label)
+      @open_navigation_label = validate_label!(:open_navigation_label, open_navigation_label)
+      @close_navigation_label = validate_label!(:close_navigation_label, close_navigation_label)
+      @navigation_dialog_label = validate_label!(:navigation_dialog_label, navigation_dialog_label)
+      @regions = REGIONS.to_h { |name| [ name, nil ] }
+      @collecting = false
+
+      super(
+        component: :app_shell,
+        attributes: {
+          id: @identifier,
+          data: {
+            controller: "nk--app-shell",
+            layout: @layout,
+            state: "closed",
+            action: "turbo:before-visit@document->nk--app-shell#closeForNavigation " \
+              "turbo:morph@document->nk--app-shell#syncViewport",
+            nk__app_shell_open_label_value: @open_navigation_label,
+            nk__app_shell_close_label_value: @close_navigation_label
+          }
+        },
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    attr_reader :identifier, :layout
+
+    def view_template(&declarations)
+      collect_regions(&declarations)
+
+      div(**root_attributes) do
+        render_skip_link
+        render_header
+        render_sidebar
+        render_dialog
+        render_main
+      end
+    end
+
+    def brand(&content)
+      add_region(:brand, content:)
+    end
+
+    def navigation(&content)
+      add_region(:navigation, content:)
+    end
+
+    def topbar(&content)
+      add_region(:topbar, content:)
+    end
+
+    def main(&content)
+      add_region(:main, content:)
+    end
+
+    private
+
+    def collect_regions
+      raise ArgumentError, "AppShell requires a declaration block" unless block_given?
+
+      @collecting = true
+      output = capture(self) { |shell| yield shell }
+      unless output.empty?
+        raise ArgumentError, "AppShell render block accepts region declarations, not rendered content"
+      end
+      REQUIRED_REGIONS.each do |region|
+        next if @regions.fetch(region)
+
+        raise ArgumentError, "AppShell requires exactly one #{region} region"
+      end
+    ensure
+      @collecting = false
+    end
+
+    def add_region(name, content:)
+      unless @collecting
+        raise ArgumentError, "AppShell #{name} must be declared directly inside the render block"
+      end
+      if @regions.fetch(name)
+        limit = REQUIRED_REGIONS.include?(name) ? "exactly one" : "at most one"
+        raise ArgumentError, "AppShell accepts #{limit} #{name} region"
+      end
+      raise ArgumentError, "AppShell #{name} requires a block" unless content
+
+      @regions[name] = content
+      nil
+    end
+
+    def region(name)
+      @regions.fetch(name)
+    end
+
+    def render_skip_link
+      a(**slot_attributes(:skip_link, attributes: { href: "##{main_id}" })) { @skip_link_label }
+    end
+
+    def render_header
+      header(**slot_attributes(:header)) do
+        div(**slot_attributes(:brand)) { render(region(:brand)) } if region(:brand)
+        render_mobile_trigger
+        div(**slot_attributes(:topbar)) { render(region(:topbar)) } if region(:topbar)
+      end
+    end
+
+    def render_mobile_trigger
+      button(
+        **slot_attributes(
+          :mobile_trigger,
+          attributes: {
+            type: "button",
+            aria: {
+              controls: drawer_id,
+              expanded: false,
+              label: @open_navigation_label
+            },
+            data: {
+              nk__app_shell_target: "trigger",
+              action: "click->nk--app-shell#toggle"
+            }
+          }
+        )
+      ) { render(Icon.new(:menu, size: :sm)) }
+    end
+
+    def render_sidebar
+      div(
+        **slot_attributes(
+          :sidebar,
+          attributes: {
+            data: { nk__app_shell_target: "sidebar" }
+          }
+        )
+      ) do
+        div(
+          **slot_attributes(
+            :navigation,
+            attributes: { data: { nk__app_shell_target: "navigation" } }
+          )
+        ) { render(region(:navigation)) }
+      end
+    end
+
+    def render_dialog
+      dialog(
+        **slot_attributes(
+          :dialog,
+          attributes: {
+            id: drawer_id,
+            aria: { label: @navigation_dialog_label },
+            data: {
+              nk__app_shell_target: "dialog",
+              action: [
+                "close->nk--app-shell#dialogClosed",
+                "click->nk--app-shell#closeFromBackdrop"
+              ].join(" ")
+            }
+          }
+        )
+      ) { render_mobile_close }
+    end
+
+    def render_mobile_close
+      button(
+        **slot_attributes(
+          :mobile_close,
+          attributes: {
+            type: "button",
+            aria: { label: @close_navigation_label },
+            data: { action: "click->nk--app-shell#close" }
+          }
+        )
+      ) { render(Icon.new(:x, size: :sm)) }
+    end
+
+    def render_main
+      html_main(**slot_attributes(:main, attributes: { id: main_id, tabindex: -1 })) { render(region(:main)) }
+    end
+
+    def drawer_id
+      "#{identifier}-navigation-drawer"
+    end
+
+    def main_id
+      "#{identifier}-main"
+    end
+
+    def component_id(value)
+      return value if value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+
+      raise ArgumentError, "AppShell id must be a fragment-safe String using letters, numbers, underscores, or hyphens"
+    end
+
+    def validate_label!(name, value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, "AppShell #{name} must be a non-blank String"
+    end
+  end
+end

data/app/components/nitro_kit/appearance_bootstrap.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class AppearanceBootstrap < Phlex::HTML
+    PREFERENCES = %i[light dark system].freeze
+    STORAGE_KEY = "nitro-kit-appearance"
+
+    SCRIPT = <<~JAVASCRIPT.freeze
+      (() => {
+        const preferences = ["light", "dark", "system"]
+        const storageKey = "nitro-kit-appearance"
+        const requestEvent = "nitro-kit:appearance-request"
+        const changeEvent = "nitro-kit:appearance-change"
+        const runtimeKey = Symbol.for("nitro-kit.appearance")
+        const suppliedDefault = document.currentScript?.dataset.nkAppearanceDefault
+        const valid = (value) => preferences.includes(value)
+        const initialDefault = valid(suppliedDefault) ? suppliedDefault : "system"
+        const existingRuntime = window[runtimeKey]
+
+        if (existingRuntime) {
+          existingRuntime.start(initialDefault)
+          return
+        }
+
+        const root = document.documentElement
+        const system = window.matchMedia("(prefers-color-scheme: dark)")
+        let defaultPreference = initialDefault
+        let preference = initialDefault
+        let mediaListening = false
+        let started = false
+
+        const read = () => {
+          try {
+            const stored = window.localStorage.getItem(storageKey)
+            return valid(stored) ? stored : defaultPreference
+          } catch (_error) {
+            return defaultPreference
+          }
+        }
+
+        const write = (value) => {
+          try {
+            window.localStorage.setItem(storageKey, value)
+          } catch (_error) {
+            // The in-document preference still works when storage is unavailable.
+          }
+        }
+
+        const resolve = () => {
+          if (preference !== "system") return preference
+          return system.matches ? "dark" : "light"
+        }
+
+        const broadcast = (theme) => {
+          window.dispatchEvent(new CustomEvent(changeEvent, {
+            detail: { preference, theme }
+          }))
+        }
+
+        const reflect = () => {
+          const theme = resolve()
+          const changed = root.dataset.themePreference !== preference || root.dataset.theme !== theme
+
+          root.dataset.themePreference = preference
+          root.dataset.theme = theme
+          if (changed) broadcast(theme)
+        }
+
+        const handleMediaChange = () => reflect()
+
+        const synchronizeMediaListener = () => {
+          if (preference === "system" && !mediaListening) {
+            system.addEventListener("change", handleMediaChange)
+            mediaListening = true
+          } else if (preference !== "system" && mediaListening) {
+            system.removeEventListener("change", handleMediaChange)
+            mediaListening = false
+          }
+        }
+
+        const apply = (nextPreference, persist = false) => {
+          if (!valid(nextPreference)) return
+
+          preference = nextPreference
+          synchronizeMediaListener()
+          if (persist) write(preference)
+          reflect()
+        }
+
+        const handleRequest = (event) => {
+          apply(event.detail?.preference, true)
+        }
+
+        const handleStorage = (event) => {
+          if (event.key !== storageKey) return
+          apply(valid(event.newValue) ? event.newValue : defaultPreference)
+        }
+
+        const runtime = {
+          start(nextDefault) {
+            if (valid(nextDefault)) defaultPreference = nextDefault
+
+            if (!started) {
+              window.addEventListener(requestEvent, handleRequest)
+              window.addEventListener("storage", handleStorage)
+              started = true
+            }
+
+            apply(read())
+          }
+        }
+
+        window[runtimeKey] = runtime
+        runtime.start(initialDefault)
+      })()
+    JAVASCRIPT
+
+    CSP_HASH = "sha256-Vcime4euWSeYtHSfjYjqz/XhRyzMcLpn6Ip2LlaHleY="
+
+    def initialize(default: :system, nonce: nil)
+      @default = validate_default!(default)
+      @nonce = validate_nonce!(nonce)
+    end
+
+    def view_template
+      script(
+        nonce: @nonce,
+        data: { nk_appearance_default: @default }
+      ) { raw safe(SCRIPT) }
+    end
+
+    private
+
+    def validate_default!(value)
+      return value if PREFERENCES.include?(value)
+
+      raise ArgumentError, "Unknown appearance default #{value.inspect}; expected one of: :light, :dark, :system"
+    end
+
+    def validate_nonce!(value)
+      return value if value.nil? || (value.is_a?(String) && !value.strip.empty?)
+
+      raise ArgumentError, "AppearanceBootstrap nonce must be a non-blank String or nil"
+    end
+  end
+end

data/app/components/nitro_kit/appearance_picker.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class AppearancePicker < Component
+    PRESENTATIONS = %i[segmented radios select dropdown].freeze
+    PREFERENCES = %i[light dark system].freeze
+    ICONS = {
+      light: :sun,
+      dark: :moon,
+      system: :monitor
+    }.freeze
+
+    def initialize(
+      id:,
+      label: I18n.t("nitro_kit.appearance_picker.label"),
+      presentation: :segmented,
+      preference: :system,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      @identifier = component_id(id)
+      @label = validate_label!(label)
+      @presentation = validate_choice!(:presentation, presentation, PRESENTATIONS)
+      @preference = validate_choice!(:preference, preference, PREFERENCES)
+
+      super(
+        component: :appearance_picker,
+        attributes: {
+          id: @identifier,
+          data: {
+            controller: "nk--appearance",
+            presentation: @presentation,
+            state: @preference,
+            action: "change->nk--appearance#select nitro-kit:appearance-change@window->nk--appearance#synchronize"
+          }
+        },
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    attr_reader :identifier, :preference
+
+    def view_template
+      return render_select if @presentation == :select
+      return render_dropdown if @presentation == :dropdown
+
+      fieldset(**root_attributes) do
+        legend(**slot_attributes(:legend)) { plain(@label) }
+        div(**slot_attributes(:options)) do
+          PREFERENCES.each { |preference| render_option(preference) }
+        end
+      end
+    end
+
+    private
+
+    def preference_label(preference)
+      I18n.t("nitro_kit.appearance_picker.preferences.#{preference}")
+    end
+
+    def render_dropdown
+      div(**root_attributes) do
+        render Dropdown.new(id: "#{identifier}-dropdown", placement: :bottom_end) do |menu|
+          menu.trigger(
+            variant: :ghost,
+            icon: ICONS.fetch(@preference),
+            label: @label,
+            data: { nk__appearance_target: "trigger" }
+          )
+          menu.title(@label)
+          PREFERENCES.each do |option|
+            menu.item(
+              preference_label(option),
+              icon: ICONS.fetch(option),
+              data: {
+                appearance_preference: option,
+                nk__appearance_target: "input",
+                action: "click->nk--appearance#select"
+              }
+            )
+          end
+        end
+      end
+    end
+
+    def render_select
+      label(**root_attributes) do
+        span(**slot_attributes(:legend)) { plain(@label) }
+        select(
+          **slot_attributes(
+            :select,
+            data: {
+              nk__appearance_target: "input",
+              action: "change->nk--appearance#select"
+            }
+          )
+        ) do
+          PREFERENCES.each do |value|
+            option(value:, selected: value == @preference) do
+              plain(preference_label(value))
+            end
+          end
+        end
+      end
+    end
+
+    def render_option(preference)
+      label(
+        **slot_attributes(
+          :option,
+          attributes: { for: option_id(preference) }
+        )
+      ) do
+        input(
+          **slot_attributes(
+            :control,
+            attributes: {
+              id: option_id(preference),
+              type: "radio",
+              name: "#{identifier}-preference",
+              value: preference,
+              checked: preference == @preference,
+              data: { nk__appearance_target: "input" }
+            }
+          )
+        )
+        span(**slot_attributes(:label)) { plain(preference_label(preference)) }
+      end
+    end
+
+    def option_id(preference)
+      "#{identifier}-#{preference}"
+    end
+
+    # Private copy of the AppShell identifier contract. Extract a shared
+    # validator into Component once its owner lands.
+    def component_id(value)
+      return value if value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+
+      raise ArgumentError,
+        "AppearancePicker id must be a String starting with a letter or digit and containing " \
+        "only letters, digits, hyphens, and underscores"
+    end
+
+    def validate_label!(value)
+      return value if value.is_a?(String) && value.present?
+
+      raise ArgumentError, "AppearancePicker label must be a non-blank String"
+    end
+  end
+end

data/app/components/nitro_kit/auth_shell.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module NitroKit
+  class AuthShell < Component
+    def initialize(
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      super(
+        component: :auth_shell,
+        attributes: { id: }.compact,
+        html:,
+        aria:,
+        data:,
+        desperately_need_a_class:
+      )
+    end
+
+    def view_template
+      raise ArgumentError, "NitroKit::AuthShell requires a content block" unless block_given?
+
+      main(**root_attributes) do
+        render NitroKit::Container.new(size: :md) do
+          render NitroKit::Flex.new(dir: :col, gap: 6, align: :stretch) do
+            yield
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/nitro_kit/avatar.rb

@@ -2,51 +2,107 @@
 
 module NitroKit
   class Avatar < Component
-    include Phlex::Rails::Helpers::ImageTag
+    SIZES = %i[xs sm md lg].freeze
 
-    def initialize(src_arg = nil, src: nil, size: :md, **attrs)
-      @src = src_arg || src
-      @size = size
+    def initialize(
+      src: nil,
+      alt: "",
+      fallback: nil,
+      size: :md,
+      loading: "lazy",
+      decoding: "async",
+      id: nil,
+      html: {},
+      aria: {},
+      data: {},
+      desperately_need_a_class: nil
+    )
+      raise ArgumentError, "alt must be a String" unless alt.is_a?(String)
+      unless fallback.nil? || fallback.is_a?(String)
+        raise ArgumentError, "fallback must be a String or nil"
+      end
+
+      @src = src
+      @alt = alt
+      @fallback = fallback || initials_for(alt)
+      @size = validate_choice!(:size, size, SIZES)
+      root_aria = fallback_aria(aria)
 
       super(
-        attrs,
-        class: [ container_class, size_classes ]
+        component: :avatar,
+        attributes: {
+          id:,
+          role: !src? && !alt.empty? ? "img" : nil,
+          data: { controller: src? ? "nk--avatar" : nil }.compact
+        },
+        html:,
+        aria: root_aria,
+        data:,
+        size:,
+        desperately_need_a_class:
       )
+
+      @image_attributes = {
+        alt:,
+        loading:,
+        decoding:
+      }
     end
 
-    attr_reader :src, :size
+    attr_reader :src, :alt, :fallback, :size
 
-    def view_template(&block)
-      div(**attrs) do
-        image
-      end
-    end
+    def view_template
+      span(**root_attributes) do
+        span(
+          **slot_attributes(
+            :fallback,
+            attributes: src? ? { data: { nk__avatar_target: "fallback" } } : {},
+            aria: { hidden: (src? || !alt.empty?) ? true : nil }
+          )
+        ) { fallback }
 
-    def image
-      image_tag(src, class: image_class)
+        if src?
+          img(
+            **slot_attributes(
+              :image,
+              attributes: @image_attributes.merge(
+                src:,
+                data: {
+                  nk__avatar_target: "image",
+                  action: "error->nk--avatar#failed"
+                }
+              )
+            )
+          )
+        end
+      end
     end
 
     private
 
-    def size_classes
-      case size
-      when :sm
-        "size-8"
-      when :md
-        "size-12"
-      when :lg
-        "size-16"
-      else
-        raise ArgumentError, "Invalid size: #{size}"
-      end
+    def src?
+      !src.nil? && (!src.respond_to?(:empty?) || !src.empty?)
     end
 
-    def container_class
-      "inline-flex overflow-hidden rounded-full"
+    def fallback_aria(aria)
+      return aria if src? || alt.empty?
+      raise ArgumentError, "aria must be a Hash" unless aria.is_a?(Hash)
+
+      label_key = aria.keys.find { |key| key.to_s.downcase.tr("_", "-") == "label" }
+      label_key ? aria : { label: alt }.merge(aria)
     end
 
-    def image_class
-      "block size-full bg-muted"
+    def initials_for(name)
+      words = name.strip.split
+      return "?" if words.empty?
+
+      initials = if words.one?
+        words.first[0, 2]
+      else
+        [ words.first[0], words.last[0] ].join
+      end
+
+      initials.upcase
     end
   end
 end