kozenet_ui 0.1.4 → 0.1.6

data/app/assets/stylesheets/kozenet_ui/tokens.css

@@ -3,6 +3,8 @@
 
 @layer base {
   :root {
+    color-scheme: light;
+
     /* Spacing */
     --kz-spacing-xs: 0.25rem;
     --kz-spacing-sm: 0.5rem;
@@ -54,6 +56,7 @@
 
     /* Default Light Mode Colors */
     --kz-bg-base: #ffffff;
+    --kz-bg-default: var(--kz-bg-base);
     --kz-bg-elevated: #f8fafc;
     --kz-bg-muted: #f1f5f9;
     --kz-text-default: #0f172a;
@@ -69,15 +72,15 @@
     --kz-cta-text: #fff;
     --kz-cta-text-dark: #fff;
 
-    --bg-default: #ffffff;
-    --bg-muted: #f8fafc;
-    --bg-elevated: #ffffff;
+    --bg-default: var(--kz-bg-base);
+    --bg-muted: var(--kz-bg-muted);
+    --bg-elevated: var(--kz-bg-elevated);
     --bg-accent: #0ea5e9;
     --bg-accent-hover: #0284c7;
-    --text-default: #0f172a;
-    --text-muted: #64748b;
-    --border-default: #e2e8f0;
-    --border-strong: #cbd5e1;
+    --text-default: var(--kz-text-default);
+    --text-muted: var(--kz-text-muted);
+    --border-default: var(--kz-border-default);
+    --border-strong: var(--kz-border-default);
     --focus-ring: #0ea5e9;
     --radius-xs: 2px;
     --radius-sm: 4px;
@@ -98,26 +101,28 @@
   /* Dark Mode */
   [data-theme="dark"],
   .dark {
-    --kz-bg-base: #0f172a;
-    --kz-bg-elevated: #1e293b;
-    --kz-bg-muted: #334155;
-    --kz-text-default: #f1f5f9;
-    --kz-text-muted: #94a3b8;
-    --kz-border-default: #334155;
-    --kz-border-muted: #1e293b;
+    color-scheme: dark;
+    --kz-bg-base: #101318;
+    --kz-bg-default: var(--kz-bg-base);
+    --kz-bg-elevated: #181c23;
+    --kz-bg-muted: #242a35;
+    --kz-text-default: #f8fafc;
+    --kz-text-muted: #cbd5e1;
+    --kz-border-default: #303744;
+    --kz-border-muted: #242a35;
 
     --kz-cta-gradient: var(--kz-cta-gradient-dark);
     --kz-cta-text: var(--kz-cta-text-dark);
 
-    --bg-default: #0b0d11;
-    --bg-muted: #11151c;
-    --bg-elevated: rgba(23,28,36,0.9);
+    --bg-default: var(--kz-bg-base);
+    --bg-muted: var(--kz-bg-muted);
+    --bg-elevated: var(--kz-bg-elevated);
     --bg-accent: #0284c7;
     --bg-accent-hover: #0369a1;
-    --text-default: #f1f5f9;
-    --text-muted: #64748b;
-    --border-default: #1f242c;
-    --border-strong: #2a3039;
+    --text-default: var(--kz-text-default);
+    --text-muted: var(--kz-text-muted);
+    --border-default: var(--kz-border-default);
+    --border-strong: var(--kz-border-default);
     --focus-ring: #0ea5e9;
     --shadow-color: 210 40% 2%;
     --gradient-base-from: #0b0d11;
@@ -129,40 +134,132 @@
     --gradient-spot-2: rgba(99,102,241,0.18);
   }
 
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]):not(.light) {
+      color-scheme: dark;
+      --kz-bg-base: #101318;
+      --kz-bg-default: var(--kz-bg-base);
+      --kz-bg-elevated: #181c23;
+      --kz-bg-muted: #242a35;
+      --kz-text-default: #f8fafc;
+      --kz-text-muted: #cbd5e1;
+      --kz-border-default: #303744;
+      --kz-border-muted: #242a35;
+
+      --kz-cta-gradient: var(--kz-cta-gradient-dark);
+      --kz-cta-text: var(--kz-cta-text-dark);
+
+      --bg-default: var(--kz-bg-base);
+      --bg-muted: var(--kz-bg-muted);
+      --bg-elevated: var(--kz-bg-elevated);
+      --bg-accent: #0284c7;
+      --bg-accent-hover: #0369a1;
+      --text-default: var(--kz-text-default);
+      --text-muted: var(--kz-text-muted);
+      --border-default: var(--kz-border-default);
+      --border-strong: var(--kz-border-default);
+      --focus-ring: #0ea5e9;
+      --shadow-color: 210 40% 2%;
+      --gradient-base-from: #0b0d11;
+      --gradient-base-to: #11151c;
+      --gradient-accent-from: #1e40af;
+      --gradient-accent-via: #0369a1;
+      --gradient-accent-to: #0891b2;
+      --gradient-spot-1: rgba(56,189,248,0.20);
+      --gradient-spot-2: rgba(99,102,241,0.18);
+    }
+  }
+
+  [data-theme="light"],
+  .light {
+    color-scheme: light;
+    --kz-bg-base: #ffffff;
+    --kz-bg-default: var(--kz-bg-base);
+    --kz-bg-elevated: #f8fafc;
+    --kz-bg-muted: #f1f5f9;
+    --kz-text-default: #0f172a;
+    --kz-text-muted: #64748b;
+    --kz-border-default: #e2e8f0;
+    --kz-border-muted: #f1f5f9;
+
+    --kz-cta-gradient: linear-gradient(110deg, #6366f1, #0ea5e9 55%, #06b6d4);
+    --kz-cta-text: #fff;
+
+    --bg-default: var(--kz-bg-base);
+    --bg-muted: var(--kz-bg-muted);
+    --bg-elevated: var(--kz-bg-elevated);
+    --bg-accent: #0ea5e9;
+    --bg-accent-hover: #0284c7;
+    --text-default: var(--kz-text-default);
+    --text-muted: var(--kz-text-muted);
+    --border-default: var(--kz-border-default);
+    --border-strong: var(--kz-border-default);
+    --focus-ring: #0ea5e9;
+    --shadow-color: 210 40% 2%;
+    --gradient-base-from: #f0f9ff;
+    --gradient-base-to: #e0f2fe;
+    --gradient-accent-from: #6366f1;
+    --gradient-accent-via: #0ea5e9;
+    --gradient-accent-to: #06b6d4;
+    --gradient-spot-1: rgba(99,102,241,0.35);
+    --gradient-spot-2: rgba(14,165,233,0.30);
+  }
+
   html { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
   body { background: var(--bg-default); color: var(--text-default); font-family: var(--font-sans, ui-sans-serif, system-ui, sans-serif); }
   * { border-color: var(--border-default); }
   ::selection { background: var(--bg-accent); color: #fff; }
-  .app-bg { 
-    position: relative;
-    min-height: 100vh;
-    overflow-x: hidden;
-    isolation: isolate;
-  }
-  .app-bg:not(:first-of-type) { background: none !important; }
-  .app-bg::before { 
-    content: "";
-    position: fixed; inset:0; pointer-events:none; z-index:-1;
-    background:
-      radial-gradient(circle at 18% 22%, var(--gradient-spot-1) 0, transparent 60%),
-      radial-gradient(circle at 82% 18%, var(--gradient-spot-2) 0, transparent 62%),
-      linear-gradient(135deg, var(--gradient-base-from) 0%, var(--gradient-base-to) 100%);
-    background-attachment: fixed;
-  }
-  .dark .app-bg::before {
-    background:
-      radial-gradient(circle at 18% 22%, var(--gradient-spot-1) 0, transparent 60%),
-      radial-gradient(circle at 82% 18%, var(--gradient-spot-2) 0, transparent 62%),
-      linear-gradient(140deg, var(--gradient-base-from) 0%, var(--gradient-base-to) 100%);
-  }
-  .app-bg::after { 
-    content: "";
-    position: fixed; inset:0; pointer-events:none; z-index:-1; mix-blend-mode:overlay;
-    background: linear-gradient(120deg, var(--gradient-accent-from), var(--gradient-accent-via) 55%, var(--gradient-accent-to));
-    opacity: .07; border-radius: inherit;
-  }
-  .dark .app-bg::after { opacity:.10; }
-  @supports (-webkit-touch-callout: none) {
-    .app-bg::before, .app-bg::after { position: absolute; }
+}
+
+/* ── App Background Utility ────────────────────────────────────────────
+ * Lives OUTSIDE @layer so its resets always beat browser defaults and
+ * un-layered host-app CSS (e.g. Rails' default `body { margin: 8px }`).
+ * This is intentional: .app-bg is an opt-in utility, and when a consumer
+ * applies it to <body>, it must guarantee zero margin/padding so that
+ * sticky headers, full-bleed sections, etc. work edge-to-edge.
+ * ──────────────────────────────────────────────────────────────────── */
+.app-bg {
+  position: relative;
+  overflow-x: hidden;
+  isolation: isolate;
+  margin: 0;
+  padding: 0;
+}
+
+.app-bg:not(:first-of-type) { background: none !important; }
+
+.app-bg::before {
+  content: "";
+  position: fixed; inset: 0; pointer-events: none; z-index: -1;
+  background:
+    radial-gradient(circle at 18% 22%, var(--gradient-spot-1) 0, transparent 60%),
+    radial-gradient(circle at 82% 18%, var(--gradient-spot-2) 0, transparent 62%),
+    linear-gradient(135deg, var(--gradient-base-from) 0%, var(--gradient-base-to) 100%);
+  background-attachment: fixed;
+}
+
+.dark .app-bg::before {
+  background:
+    radial-gradient(circle at 18% 22%, var(--gradient-spot-1) 0, transparent 60%),
+    radial-gradient(circle at 82% 18%, var(--gradient-spot-2) 0, transparent 62%),
+    linear-gradient(140deg, var(--gradient-base-from) 0%, var(--gradient-base-to) 100%);
+}
+
+.app-bg::after {
+  content: "";
+  position: fixed; inset: 0; pointer-events: none; z-index: -1; mix-blend-mode: overlay;
+  background: linear-gradient(120deg, var(--gradient-accent-from), var(--gradient-accent-via) 55%, var(--gradient-accent-to));
+  opacity: .07; border-radius: inherit;
+}
+
+.dark .app-bg::after { opacity: .10; }
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]):not(.light) .app-bg::after {
+    opacity: .10;
   }
-}
+}
+
+@supports (-webkit-touch-callout: none) {
+  .app-bg::before, .app-bg::after { position: absolute; }
+}

data/app/components/kozenet_ui/base_component.rb

@@ -4,6 +4,8 @@ module KozenetUi
   # Base component that all Kozenet UI components inherit from
   # Provides common functionality for variant handling, class merging, etc.
   class BaseComponent < ViewComponent::Base
+    UNSET = Object.new.freeze
+
     attr_reader :variant, :size, :html_options
 
     def initialize(variant: nil, size: nil, class: nil, **html_options)
@@ -78,7 +80,25 @@ module KozenetUi
 
     # Stimulus controller name with prefix
     def stimulus_controller(name)
-      "#{KozenetUi.configuration.stimulus_prefix}-#{name}"
+      "#{KozenetUi.configuration.stimulus_prefix}-#{name.to_s.tr("_", "-")}"
+    end
+
+    def stimulus_controllers(*names)
+      names.map { |name| stimulus_controller(name) }.join(" ")
+    end
+
+    def stimulus_action(controller, action, event:)
+      "#{event}->#{stimulus_controller(controller)}##{action}"
+    end
+
+    def stimulus_target(controller, target)
+      { "data-#{stimulus_controller(controller)}-target" => target.to_s.tr("_", "-") }
+    end
+
+    def component_option(component, option, value = UNSET, fallback: nil)
+      return value unless value.equal?(UNSET)
+
+      KozenetUi.configuration.component_defaults_for(component).fetch(option.to_sym, fallback)
     end
   end
 end

data/app/components/kozenet_ui/header_component/action_button_component.html.erb

@@ -1,11 +1,13 @@
 <%# frozen_string_literal: true %>
 <%# ActionButtonComponent template for KozenetUi::HeaderComponent %>
-<%= tag.a href: @href, class: "kz-action-btn", aria: { label: @label } do %>
+<%= tag.a(**action_button_attrs) do %>
   <% if @icon %>
     <span class="kz-action-btn-icon"><%= render_icon(@icon) %></span>
   <% end %>
   <% if @label %>
     <span class="kz-action-btn-label"><%= @label %></span>
   <% end %>
-  <%= content if content.present? %>
+  <% if visible_text? %>
+    <span class="kz-action-btn-text"><%= visible_text %></span>
+  <% end %>
 <% end %>

data/app/components/kozenet_ui/header_component/action_button_component.rb

@@ -6,23 +6,97 @@ module KozenetUi
     # Renders an action button (icon or text) in the header
     #
     # @example
-    #   <%= render KozenetUi::HeaderComponent::ActionButtonComponent.new(href: "/cart", icon: :cart, label: "Cart") %>
+    #   <%= render KozenetUi::HeaderComponent::ActionButtonComponent.new(href: "/cart", icon: :shopping_cart, label: "Cart") %>
     class ActionButtonComponent < BaseComponent
-      def initialize(href: "#", icon: nil, label: nil, **html_options)
+      PLACEMENTS = %i[start end].freeze
+      PLACEMENT_ALIASES = {
+        before: :start,
+        left: :start,
+        right: :end,
+        after: :end
+      }.freeze
+      VISIBILITIES = %i[always desktop mobile].freeze
+      VISIBILITY_ALIASES = {
+        all: :always,
+        both: :always
+      }.freeze
+
+      attr_reader :placement
+      attr_reader :visible_on
+
+      def initialize(
+        href: "#",
+        icon: nil,
+        text: nil,
+        label: nil,
+        placement: :end,
+        position: nil,
+        visible_on: :desktop,
+        **html_options
+      )
         super(**html_options)
         @href = href
         @icon = icon
+        @text = text
         @label = label
+        @placement = normalize_placement(position || placement)
+        @visible_on = normalize_visibility(visible_on)
       end
 
       private
 
+      def action_button_attrs
+        attrs = html_options.merge(
+          href: @href,
+          class: action_button_classes
+        )
+        attrs[:aria] = action_button_aria if action_button_aria.any?
+        attrs
+      end
+
       def action_button_classes
-        "kz-action-btn"
+        classes = ["kz-action-btn"]
+        classes << "kz-action-btn-with-text" if visible_text?
+        classes << "kz-action-btn-placement-#{placement}"
+        classes << "kz-action-visible-#{visible_on}"
+        classes << @custom_class if defined?(@custom_class) && @custom_class
+        classes.join(" ")
+      end
+
+      def action_button_aria
+        aria = html_options.fetch(:aria, {}).dup
+        aria[:label] = @label if @label.present?
+        aria
+      end
+
+      def visible_text
+        @text.presence || (content if content.present?)
+      end
+
+      def visible_text?
+        visible_text.present?
       end
 
       def render_icon(icon)
-        ApplicationController.helpers.kozenet_ui_icon(icon, class: "kz-action-btn-icon") if icon
+        return unless icon
+
+        helpers.kozenet_ui_icon(icon, class: "kz-action-btn-svg", size: 20)
+      end
+
+      def normalize_placement(value)
+        normalized_value = value.to_s.tr("-", "_").to_sym
+        normalized_value = PLACEMENT_ALIASES.fetch(normalized_value, normalized_value)
+        return normalized_value if PLACEMENTS.include?(normalized_value)
+
+        raise ArgumentError, "Unknown header action placement `#{value}`. Use :start or :end."
+      end
+
+      def normalize_visibility(value)
+        normalized_value = value.to_s.tr("-", "_").to_sym
+        normalized_value = VISIBILITY_ALIASES.fetch(normalized_value, normalized_value)
+        return normalized_value if VISIBILITIES.include?(normalized_value)
+
+        raise ArgumentError, "Unknown header action visibility `#{value}`. Use :always, :desktop, or :mobile."
       end
     end
   end

data/app/components/kozenet_ui/header_component/nav_item_component.html.erb

@@ -1,6 +1,6 @@
 <%# frozen_string_literal: true %>
 <%# NavItemComponent template for KozenetUi::HeaderComponent %>
-<%= tag.a href: @href, class: nav_item_classes, role: (@dropdown ? "button" : nil), data: (@dropdown ? { action: "click->kz-dropdown#toggle" } : {}) do %>
+<%= tag.a href: @href, class: nav_item_classes, role: (@dropdown ? "button" : nil), data: nav_item_data do %>
   <%= content %>
   <% if @dropdown %>
     <svg class="ml-1 opacity-60" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>

data/app/components/kozenet_ui/header_component/nav_item_component.rb

@@ -23,6 +23,12 @@ module KozenetUi
         classes << @custom_class if defined?(@custom_class) && @custom_class
         classes.join(" ")
       end
+
+      def nav_item_data
+        return {} unless @dropdown
+
+        { action: stimulus_action(:dropdown, :toggle, event: :click) }
+      end
     end
   end
 end

data/app/components/kozenet_ui/header_component/user_menu_component.html.erb

@@ -1,18 +1,16 @@
 <%# frozen_string_literal: true %>
 <%# UserMenuComponent template for KozenetUi::HeaderComponent %>
-<div class="kz-user-menu relative" data-controller="kz-user-menu">
-  <button type="button" class="kz-avatar-btn flex items-center gap-2" data-action="click->kz-user-menu#toggle">
+<div class="kz-user-menu" data-controller="<%= stimulus_controller(:user_menu) %>">
+  <button type="button" class="kz-avatar-btn" data-action="<%= stimulus_action(:user_menu, :toggle, event: :click) %>">
     <% if @avatar_url.present? %>
-      <img src="<%= @avatar_url %>" alt="<%= @user_name %>" class="w-8 h-8 rounded-full" />
+      <img src="<%= @avatar_url %>" alt="<%= @user_name %>" />
     <% else %>
-      <span class="bg-gray-300 dark:bg-gray-700 w-8 h-8 rounded-full flex items-center justify-center font-bold">
+      <span class="kz-user-initial">
         <%= @user_name.to_s.first.upcase %>
       </span>
     <% end %>
-    <span class="kz-user-name"><%= @user_name %></span>
-    <svg class="ml-1 w-4 h-4" viewBox="0 0 20 20" fill="currentColor"><path d="M5.23 7.21a.75.75 0 0 1 1.06.02L10 11.06l3.71-3.83a.75.75 0 1 1 1.08 1.04l-4.25 4.39a.75.75 0 0 1-1.08 0L5.21 8.27a.75.75 0 0 1 .02-1.06z"/></svg>
   </button>
-  <div class="kz-user-dropdown absolute right-0 mt-2 w-48 bg-white dark:bg-gray-900 rounded shadow-lg z-50 hidden" data-kz-user-menu-target="dropdown">
+  <div class="kz-user-dropdown hidden" <%= tag.attributes(stimulus_target(:user_menu, :dropdown)) %>>
     <%= content %>
   </div>
 </div>

data/app/components/kozenet_ui/header_component.html.erb

@@ -1,10 +1,22 @@
-<header class="kz-header kz-header-sticky kz-header-blur" data-controller="kz-header kz-mobile-nav" data-action="scroll@window->kz-header#handleScroll">
-  <div class="kz-header-bar" data-kz-header-target="container">
+<header
+  class="<%= component_classes %>"
+  data-controller="<%= stimulus_controllers(:header, :mobile_nav) %>"
+  data-action="<%= stimulus_action(:header, :handleScroll, event: "scroll@window") %>"
+>
+  <div class="kz-header-bar" <%= tag.attributes(stimulus_target(:header, :container)) %>>
     <!-- Brand + Navigation -->
     <div class="kz-header-start">
-      <div class="kz-brand">
-        <%= brand if brand? %>
-      </div>
+      <% if start_action_buttons? %>
+        <div class="kz-header-start-actions">
+          <% start_action_buttons.each do |button| %>
+            <%= button %>
+          <% end %>
+        </div>
+      <% end %>
+
+      <% if brand? %>
+        <%= brand %>
+      <% end %>
       <% if nav_items? %>
         <nav class="kz-nav-links" aria-label="Primary navigation">
           <% nav_items.each do |item| %>
@@ -25,22 +37,19 @@
     <div class="kz-header-actions">
       <!-- Mobile search trigger -->
       <% if search? %>
-        <button 
-          type="button" 
-          class="kz-action-btn md:hidden" 
+        <button
+          type="button"
+          class="kz-action-btn md:hidden"
           aria-label="Search"
-          data-action="click->kz-header#toggleSearch"
+          data-action="<%= stimulus_action(:header, :toggleSearch, event: :click) %>"
         >
-          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-            <circle cx="11" cy="11" r="8"/>
-            <path d="m21 21-4.35-4.35"/>
-          </svg>
+          <%= helpers.kozenet_ui_icon(:magnifying_glass, class: "kz-action-btn-svg", size: 20) %>
         </button>
       <% end %>
 
       <!-- Action buttons -->
-      <% if action_buttons? %>
-        <% action_buttons.each do |button| %>
+      <% if end_action_buttons? %>
+        <% end_action_buttons.each do |button| %>
           <%= button %>
         <% end %>
       <% end %>
@@ -53,29 +62,29 @@
       <% end %>
 
       <!-- Mobile menu trigger -->
-      <button 
-        class="kz-mobile-trigger" 
-        type="button"
-        aria-label="Menu"
-        data-action="click->kz-mobile-nav#toggle"
-        data-kz-mobile-nav-target="trigger"
-      >
-        <svg class="kz-icon-menu" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-          <path d="M3 6h18M3 12h18M3 18h18"/>
-        </svg>
-      </button>
+      <% if mobile_menu? %>
+        <button
+          class="kz-mobile-trigger"
+          type="button"
+          aria-label="Menu"
+          data-action="<%= stimulus_action(:mobile_nav, :toggle, event: :click) %>"
+          <%= tag.attributes(stimulus_target(:mobile_nav, :trigger)) %>
+        >
+          <%= helpers.kozenet_ui_icon(:bars_3, class: "kz-icon-menu", size: 20) %>
+        </button>
+      <% end %>
     </div>
   </div>
 
   <!-- Mobile panel -->
   <% if mobile_menu? %>
-    <div 
-      class="kz-mobile-panel hidden scale-y-0 origin-top" 
-      data-kz-mobile-nav-target="panel"
+    <div
+      class="kz-mobile-panel hidden scale-y-0 origin-top"
+      <%= tag.attributes(stimulus_target(:mobile_nav, :panel)) %>
       role="dialog"
       aria-label="Mobile navigation"
     >
       <%= mobile_menu %>
     </div>
   <% end %>
-</header>
+</header>

data/app/components/kozenet_ui/header_component.rb

@@ -19,13 +19,13 @@ module KozenetUi
     renders_one :mobile_menu
 
     def initialize(
-      sticky: true,
-      blur: true,
+      sticky: BaseComponent::UNSET,
+      blur: BaseComponent::UNSET,
       **html_options
     )
       super(**html_options)
-      @sticky = sticky
-      @blur = blur
+      @sticky = component_option(:header, :sticky, sticky, fallback: true)
+      @blur = component_option(:header, :blur, blur, fallback: true)
     end
 
     private
@@ -36,5 +36,27 @@ module KozenetUi
       classes << "kz-header-blur" if @blur
       classes.join(" ")
     end
+
+    def start_action_buttons
+      action_buttons_for(:start)
+    end
+
+    def start_action_buttons?
+      start_action_buttons.any?
+    end
+
+    def end_action_buttons
+      action_buttons_for(:end)
+    end
+
+    def end_action_buttons?
+      end_action_buttons.any?
+    end
+
+    def action_buttons_for(placement)
+      return [] unless action_buttons?
+
+      action_buttons.select { |button| button.placement == placement }
+    end
   end
 end