kozenet_ui 0.1.4 → 0.1.6

data/app/helpers/kozenet_ui/component_helper.rb

@@ -28,28 +28,102 @@ module KozenetUi
 
     # Include theme styles in layout
     def kozenet_ui_stylesheet_tag
-      stylesheet_link_tag "kozenet_ui/tokens", "kozenet_ui/base", "kozenet_ui/components"
+      stylesheet_link_tag(
+        "kozenet_ui/tokens",
+        "kozenet_ui/fonts",
+        "kozenet_ui/base",
+        "kozenet_ui/components/button",
+        "kozenet_ui/components/header",
+        "kozenet_ui/components/avatar",
+        "kozenet_ui/components/badge",
+        "kozenet_ui/components/utilities",
+        "data-turbo-track": "reload"
+      )
     end
 
     # Include theme JavaScript
     def kozenet_ui_javascript_tag
-      javascript_include_tag "kozenet_ui/index", type: "module"
+      javascript_include_tag "kozenet_ui/index", type: "module", "data-turbo-track": "reload"
+    end
+
+    # Include runtime tags once in the application layout.
+    #
+    # Stylesheets are loaded directly so Propshaft/Sprockets can emit digested
+    # asset URLs in production. Apps can pass stylesheets: false when bundling
+    # Kozenet UI CSS with their own build pipeline.
+    def kozenet_ui_head_tags(stylesheets: true, javascript: true)
+      tags = []
+      tags << kozenet_ui_stylesheet_tag if stylesheets
+      tags << kozenet_ui_config_tag
+      tags << kozenet_ui_theme_variables_tag
+      tags << kozenet_ui_javascript_tag if javascript
+
+      safe_join(tags, "\n")
+    end
+
+    def kozenet_ui_config_tag
+      tag.meta name: "kozenet-ui-stimulus-prefix", content: KozenetUi.configuration.stimulus_prefix
     end
 
     # Inject inline theme variables (CSP-compliant)
     def kozenet_ui_theme_variables_tag
       # rubocop:disable Rails/OutputSafety
-      content_tag(:style, nonce: content_security_policy_nonce) do
-        palette = KozenetUi.configuration.palette
-        tokens = KozenetUi::Theme::Tokens
+      content_tag(:style, kozenet_ui_theme_variables, nonce: content_security_policy_nonce)
+      # rubocop:enable Rails/OutputSafety
+    end
+
+    def kozenet_ui_theme_variables
+      # rubocop:disable Rails/OutputSafety
+      palette = KozenetUi.configuration.palette
+      light_palette = palette.to_css_variables(mode: :light)
+      dark_palette = palette.to_css_variables(mode: :dark)
+      tokens = KozenetUi::Theme::Tokens.to_css_variables
 
+      case KozenetUi.configuration.theme
+      when :dark, "dark"
+        <<~CSS.html_safe
+          :root {
+            color-scheme: dark;
+            #{tokens}
+            #{dark_palette}
+          }
+          [data-theme="light"], .light {
+            color-scheme: light;
+            #{light_palette}
+          }
+        CSS
+      when :system, "system"
+        <<~CSS.html_safe
+          :root {
+            color-scheme: light;
+            #{tokens}
+            #{light_palette}
+          }
+          @media (prefers-color-scheme: dark) {
+            :root:not([data-theme="light"]) {
+              color-scheme: dark;
+              #{dark_palette}
+            }
+          }
+          [data-theme="dark"], .dark {
+            color-scheme: dark;
+            #{dark_palette}
+          }
+          [data-theme="light"], .light {
+            color-scheme: light;
+            #{light_palette}
+          }
+        CSS
+      else
         <<~CSS.html_safe
           :root {
-            #{tokens.to_css_variables}
-            #{palette.to_css_variables(mode: :light)}
+            color-scheme: light;
+            #{tokens}
+            #{light_palette}
           }
           [data-theme="dark"], .dark {
-            #{palette.to_css_variables(mode: :dark)}
+            color-scheme: dark;
+            #{dark_palette}
           }
         CSS
       end

data/app/helpers/kozenet_ui/icon_helper.rb

@@ -3,14 +3,18 @@
 module KozenetUi
   # Helper methods for rendering SVG icons in Kozenet UI
   module IconHelper
-    # Renders a Heroicon SVG from the gem's assets
-    # Usage: kozenet_ui_icon(:cart, class: "w-5 h-5 text-gray-500")
+    include RailsHeroicon::Helper
+
     def kozenet_ui_icon(name, options = {})
-      app_path = "icons/#{name}.svg"
-      gem_path = "kozenet_ui/icons/#{name}.svg"
-      app_full_path = Rails.root.join("app/assets/images", app_path)
-      path = File.exist?(app_full_path) ? app_path : gem_path
-      image_tag(asset_path(path), options)
+      heroicon(normalize_icon_name(name), **options)
+    rescue RailsHeroicon::UndefinedIcon => e
+      raise ArgumentError, "Unknown Heroicon `#{name}`. Use a valid icon name from Heroicons.", e.backtrace
+    end
+
+    private
+
+    def normalize_icon_name(name)
+      name.to_s.tr("_", "-")
     end
   end
 end

data/docs/README.md

@@ -0,0 +1,25 @@
+# Kozenet UI Docs
+
+This folder documents how to use Kozenet UI as a Rails gem.
+
+## Foundations
+
+Foundations are the shared UI base used by every component.
+
+- [Fonts](./foundations/fonts.md)
+
+## Components
+
+Components are the public ViewComponent APIs used in Rails views.
+
+- [Component Docs](./components/README.md)
+- [Avatar](./components/avatar.md)
+- [Badge](./components/badge.md)
+- [Button](./components/button.md)
+- [Header](./components/header.md)
+
+## Adding New Docs
+
+When adding a new component, add one Markdown file in `docs/components`.
+
+When adding a shared system feature, add one Markdown file in `docs/foundations`.

data/docs/components/README.md

@@ -0,0 +1,44 @@
+# Component Docs
+
+This folder is the public usage guide for Kozenet UI components. Each component gets one Markdown file with the same shape so the documentation can grow without becoming messy.
+
+## Components
+
+- [Avatar](./avatar.md)
+- [Badge](./badge.md)
+- [Button](./button.md)
+- [Header](./header.md)
+
+Shared UI foundations live in [../foundations](../foundations/README.md).
+
+## Documentation Pattern
+
+Each component page should include:
+
+- Purpose: when to use the component.
+- Quick usage: the recommended helper API.
+- Direct render: the ViewComponent API.
+- Options: accepted options and defaults.
+- Examples: common production patterns.
+- Best practices: how to keep apps clean, fast, and consistent.
+
+## Rails Setup
+
+Load Kozenet UI once in your application layout:
+
+```erb
+<%= javascript_importmap_tags %>
+<%= kozenet_ui_head_tags %>
+```
+
+Configure global defaults in `config/initializers/kozenet_ui.rb`:
+
+```ruby
+KozenetUi.configure do |config|
+  config.theme = :system
+  config.stimulus_prefix = "kz"
+  config.component :header, sticky: true, blur: true
+end
+```
+
+Per-render options should always win over initializer defaults.

data/docs/components/avatar.md

@@ -0,0 +1,73 @@
+# Avatar
+
+Use `AvatarComponent` for people, teams, authors, and account menu triggers.
+
+## Quick Usage
+
+```erb
+<%= kz_avatar(src: user.avatar_url, alt: user.name) %>
+```
+
+## Direct Render
+
+```erb
+<%= render KozenetUi::AvatarComponent.new(initials: "KP", variant: :primary) %>
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `src` | `nil` | Image URL. |
+| `alt` | `"Avatar"` | Image alt text. |
+| `initials` | `nil` | Text fallback when no image is present. |
+| `variant` | `:primary` | Background style for initials/default state. |
+| `size` | `:md` | Avatar size. |
+| `html_options` | `{}` | Extra HTML attributes. |
+
+## Image Avatar
+
+```erb
+<%= kz_avatar(src: current_user.avatar_url, alt: current_user.name, size: :lg) %>
+```
+
+## Initials Avatar
+
+```erb
+<%= kz_avatar(initials: "JD", variant: :accent) %>
+```
+
+## Default Icon Avatar
+
+```erb
+<%= kz_avatar %>
+```
+
+## Sizes
+
+```erb
+<%= kz_avatar(initials: "XS", size: :xs) %>
+<%= kz_avatar(initials: "SM", size: :sm) %>
+<%= kz_avatar(initials: "MD", size: :md) %>
+<%= kz_avatar(initials: "LG", size: :lg) %>
+<%= kz_avatar(initials: "XL", size: :xl) %>
+```
+
+## With Extra Attributes
+
+```erb
+<%= kz_avatar(
+  initials: "KP",
+  html_options: {
+    title: "Kozenet Pro",
+    data: { testid: "author-avatar" }
+  }
+) %>
+```
+
+## Best Practices
+
+- Always provide meaningful `alt` text for real user images.
+- Use initials when the user has no uploaded image.
+- Keep avatar size consistent inside repeated lists.
+- Use the same variant for the same identity type across an app.

data/docs/components/badge.md

@@ -0,0 +1,74 @@
+# Badge
+
+Use `BadgeComponent` for statuses, labels, counters, categories, and small metadata.
+
+## Quick Usage
+
+```erb
+<%= kz_badge(variant: :success) { "Published" } %>
+```
+
+## Direct Render
+
+```erb
+<%= render KozenetUi::BadgeComponent.new(variant: :warning, size: :sm) do %>
+  Pending
+<% end %>
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `variant` | `:primary` | Visual style. |
+| `size` | `:md` | Badge size. |
+| `pill` | `true` | Uses rounded pill shape. |
+| `**html_options` | `{}` | Extra HTML attributes. |
+
+## Variants
+
+```erb
+<%= kz_badge(variant: :primary) { "Primary" } %>
+<%= kz_badge(variant: :secondary) { "Secondary" } %>
+<%= kz_badge(variant: :accent) { "Accent" } %>
+<%= kz_badge(variant: :success) { "Success" } %>
+<%= kz_badge(variant: :warning) { "Warning" } %>
+<%= kz_badge(variant: :error) { "Error" } %>
+<%= kz_badge(variant: :info) { "Info" } %>
+```
+
+## Count Badge
+
+```erb
+<%= kz_badge(variant: :primary, size: :sm) { "99+" } %>
+```
+
+## Category Badge
+
+```erb
+<%= kz_badge(variant: :accent) { blog.category_name } %>
+```
+
+## With Icon
+
+```erb
+<%= kz_badge(variant: :warning) do |badge| %>
+  <% badge.with_icon do %>
+    <%= kozenet_ui_icon(:clock, size: 14) %>
+  <% end %>
+  Pending
+<% end %>
+```
+
+## Less Rounded
+
+```erb
+<%= kz_badge(variant: :secondary, pill: false) { "Draft" } %>
+```
+
+## Best Practices
+
+- Keep text short: one to three words.
+- Use semantic variants for state: `:success`, `:warning`, `:error`.
+- Use `:accent` for brand/category emphasis.
+- Avoid using badges as buttons. Use `kz_button` for actions.

data/docs/components/button.md

@@ -0,0 +1,95 @@
+# Button
+
+Use `ButtonComponent` for primary actions, secondary actions, links that should look like buttons, and loading or disabled states.
+
+## Quick Usage
+
+```erb
+<%= kz_button { "Save changes" } %>
+```
+
+```erb
+<%= kz_button(variant: :secondary, size: :lg) { "Preview" } %>
+```
+
+## Direct Render
+
+```erb
+<%= render KozenetUi::ButtonComponent.new(variant: :primary, size: :md) do %>
+  Save changes
+<% end %>
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `variant` | `:primary` | Visual style. |
+| `size` | `:md` | Button size. |
+| `type` | `:button` | Native button type. |
+| `href` | `nil` | Renders an anchor when present. |
+| `disabled` | `false` | Disables the action visually and semantically. |
+| `loading` | `false` | Shows spinner and marks the button busy. |
+| `full_width` | `false` | Makes the button fill the available width. |
+| `html_options` | `{}` | Extra HTML attributes. |
+
+## Variants
+
+```erb
+<%= kz_button(variant: :primary) { "Primary" } %>
+<%= kz_button(variant: :secondary) { "Secondary" } %>
+<%= kz_button(variant: :accent) { "Accent" } %>
+<%= kz_button(variant: :success) { "Success" } %>
+<%= kz_button(variant: :warning) { "Warning" } %>
+<%= kz_button(variant: :error) { "Error" } %>
+<%= kz_button(variant: :ghost) { "Ghost" } %>
+<%= kz_button(variant: :outline) { "Outline" } %>
+```
+
+## Sizes
+
+```erb
+<%= kz_button(size: :xs) { "XS" } %>
+<%= kz_button(size: :sm) { "SM" } %>
+<%= kz_button(size: :md) { "MD" } %>
+<%= kz_button(size: :lg) { "LG" } %>
+<%= kz_button(size: :xl) { "XL" } %>
+```
+
+## Link Button
+
+```erb
+<%= kz_button(href: pricing_path, variant: :ghost) { "View pricing" } %>
+```
+
+## Loading State
+
+```erb
+<%= kz_button(loading: true) { "Saving..." } %>
+```
+
+## With Icon
+
+```erb
+<%= kz_button(variant: :secondary) do |button| %>
+  <% button.with_icon do %>
+    <%= kozenet_ui_icon(:arrow_down_tray, size: 18) %>
+  <% end %>
+  Download
+<% end %>
+```
+
+## Form Submit
+
+```erb
+<%= form_with model: @post do |form| %>
+  <%= kz_button(type: :submit, variant: :primary) { "Publish" } %>
+<% end %>
+```
+
+## Best Practices
+
+- Use `:primary` for one main action per screen or section.
+- Use `:secondary`, `:ghost`, or `:outline` for supporting actions.
+- Use `loading: true` while a submission is in progress.
+- Use `href:` only for navigation. Use button submit types for forms.

data/docs/components/header.md

@@ -0,0 +1,199 @@
+# Header
+
+Use `HeaderComponent` for primary application navigation. It supports brand, nav links, search, icon actions, CTA, user menu, and mobile menu slots.
+
+## Quick Usage
+
+```erb
+<%= kz_header do |header| %>
+  <% header.with_brand(href: root_path) do %>
+    <span>Kozenet</span>
+  <% end %>
+
+  <% header.with_nav_item(href: posts_path, active: current_page?(posts_path)) { "Posts" } %>
+  <% header.with_nav_item(href: new_post_path) { "New" } %>
+
+  <% header.with_search(placeholder: "Search posts", action: posts_path, value: params[:q]) %>
+  <% header.with_action_button(href: saved_posts_path, icon: :heart, label: "Saved") %>
+  <% header.with_cta(href: new_post_path) { "New post" } %>
+<% end %>
+```
+
+## Direct Render
+
+```erb
+<%= render KozenetUi::HeaderComponent.new(sticky: true, blur: true) do |header| %>
+  <% header.with_brand(href: root_path) { "Brand" } %>
+<% end %>
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `sticky` | initializer default, fallback `true` | Keeps header sticky at top. |
+| `blur` | initializer default, fallback `true` | Enables glass/blur treatment. |
+| `**html_options` | `{}` | Extra HTML attributes. |
+
+## Global Defaults
+
+Set project defaults in `config/initializers/kozenet_ui.rb`:
+
+```ruby
+KozenetUi.configure do |config|
+  config.component :header, sticky: true, blur: true
+end
+```
+
+Override for one render:
+
+```erb
+<%= kz_header(sticky: false, blur: false) do |header| %>
+  <% header.with_brand(href: root_path) { "Plain Header" } %>
+<% end %>
+```
+
+## Slots
+
+| Slot | Purpose |
+| --- | --- |
+| `with_brand` | Brand/logo link. |
+| `with_nav_item` | Primary nav links. |
+| `with_search` | Header search form. |
+| `with_action_button` | Icon or compact text action button. |
+| `with_cta` | Main call-to-action. |
+| `with_user_menu` | Account/avatar menu. |
+| `with_mobile_menu` | Mobile navigation panel. |
+
+## Brand
+
+```erb
+<% header.with_brand(href: root_path) do %>
+  <span class="brand-mark">K</span>
+  <span>Kozenet <span class="accent">UI</span></span>
+<% end %>
+```
+
+## Nav Items
+
+```erb
+<% header.with_nav_item(href: dashboard_path, active: current_page?(dashboard_path)) { "Dashboard" } %>
+<% header.with_nav_item(href: settings_path) { "Settings" } %>
+```
+
+## Search
+
+```erb
+<% header.with_search(
+  placeholder: "Search",
+  name: :q,
+  value: params[:q],
+  action: posts_path,
+  method: :get
+) %>
+```
+
+## Action Button
+
+Action buttons use Heroicons names. Ruby-style names are normalized:
+
+```erb
+<% header.with_action_button(href: notifications_path, icon: :bell, label: "Notifications") %>
+<% header.with_action_button(href: cart_path, icon: :shopping_cart, label: "Cart") %>
+```
+
+`label` is used for accessibility and is visually hidden in the icon-only button.
+
+By default, action buttons render in the end group, on the right side of the desktop header. Use `placement: :start` for actions that belong at the left/start edge, such as a sidebar toggle:
+
+```erb
+<% header.with_action_button(href: "#", icon: :bars_3, label: "Open menu", placement: :start) %>
+<% header.with_action_button(href: saved_posts_path, icon: :heart, label: "Saved", placement: :end) %>
+```
+
+`position: :left` and `position: :right` are accepted as aliases, but `placement: :start` and `placement: :end` are preferred.
+
+Header action buttons are desktop-only by default so mobile headers stay clean. Use `visible_on:` when an action should appear somewhere else:
+
+```erb
+<% header.with_action_button(href: "#", icon: :bars_3, label: "Open menu", placement: :start, visible_on: :mobile) %>
+<% header.with_action_button(href: settings_path, icon: :cog_6_tooth, label: "Settings", visible_on: :desktop) %>
+```
+
+Accepted values are `:desktop`, `:mobile`, and `:always`. The default is `:desktop`.
+
+Use `text:` when the action should be visible as a compact text button:
+
+```erb
+<% header.with_action_button(href: saved_posts_path, text: "Saved", label: "Saved posts") %>
+```
+
+You can combine icon and text:
+
+```erb
+<% header.with_action_button(href: saved_posts_path, icon: :heart, text: "Saved", label: "Saved posts") %>
+```
+
+## CTA
+
+```erb
+<% header.with_cta(href: new_post_path) { "New post" } %>
+```
+
+## User Menu
+
+```erb
+<% header.with_user_menu(user_name: current_user.name, avatar_url: current_user.avatar_url) do %>
+  <%= link_to "Profile", profile_path, class: "menu-link" %>
+  <%= link_to "Settings", settings_path, class: "menu-link" %>
+<% end %>
+```
+
+## Mobile Menu
+
+```erb
+<% header.with_mobile_menu do %>
+  <nav aria-label="Mobile navigation">
+    <%= link_to "Posts", posts_path %>
+    <%= link_to "New post", new_post_path %>
+  </nav>
+<% end %>
+```
+
+## Full Example
+
+```erb
+<%= kz_header do |header| %>
+  <% header.with_brand(href: root_path) do %>
+    <span class="brand-mark">K</span>
+    <span>Kozenet <span class="accent">Blog</span></span>
+  <% end %>
+
+  <% header.with_nav_item(href: posts_path, active: current_page?(posts_path)) { "Posts" } %>
+  <% header.with_nav_item(href: new_post_path, active: current_page?(new_post_path)) { "New" } %>
+  <% header.with_search(placeholder: "Search posts", action: posts_path, value: params[:q]) %>
+  <% header.with_action_button(href: saved_posts_path, icon: :heart, label: "Saved") %>
+
+  <% header.with_user_menu(user_name: "Kozenet") do %>
+    <%= link_to "All posts", posts_path, class: "menu-link" %>
+    <%= link_to "New post", new_post_path, class: "menu-link" %>
+  <% end %>
+
+  <% header.with_mobile_menu do %>
+    <nav aria-label="Mobile navigation">
+      <%= link_to "Posts", posts_path %>
+      <%= link_to "New post", new_post_path %>
+    </nav>
+  <% end %>
+<% end %>
+```
+
+## Best Practices
+
+- Load `kozenet_ui_head_tags` once in the layout, not per page.
+- Prefer initializer defaults for app-wide header behavior.
+- Keep per-page overrides close to the render call.
+- Use Heroicons names for icon actions.
+- Always provide labels for icon-only actions.
+- Keep navigation items short so desktop and mobile layouts stay balanced.
+- Keep mobile actions intentional; prefer one menu/search trigger and move secondary links into `with_mobile_menu`.

data/docs/foundations/README.md

@@ -0,0 +1,14 @@
+# Foundations
+
+Foundations are the shared design and runtime pieces behind Kozenet UI components.
+
+- [Fonts](./fonts.md)
+
+Future foundation docs can live here too:
+
+- Colors
+- Theme
+- Tokens
+- Icons
+- JavaScript
+- Accessibility