kiso 0.1.0.pre → 0.2.0.pre

data/app/helpers/kiso/component_helper.rb

@@ -1,36 +1,29 @@
 module Kiso
+  # View helpers for rendering Kiso components.
+  #
+  # Included in all views automatically by {Engine}.
   module ComponentHelper
-    # Renders a component element with data-attribute API.
+    # Renders a Kiso component partial.
     #
-    #   component_tag(:span, :badge, variant: :primary, size: :md) { "Active" }
-    #   # => <span data-component="badge" data-variant="primary" data-size="md">Active</span>
+    # Components live in +app/views/kiso/components/+. Sub-parts are nested
+    # in a directory matching the parent component name.
     #
-    #   component_tag(:div, :card, part: :header) { ... }
-    #   # => <div data-card-part="header">...</div>
+    # @param component [Symbol] the component name (e.g. +:badge+, +:card+)
+    # @param part [Symbol, nil] optional sub-part name (e.g. +:header+, +:footer+)
+    # @param collection [Array, nil] renders the partial once per item when present
+    # @param kwargs [Hash] locals passed to the partial (e.g. +color:+, +variant:+, +css_classes:+)
+    # @yield optional block for component content
+    # @return [ActiveSupport::SafeBuffer] rendered HTML
     #
-    def component_tag(element, component, variant: nil, size: nil, part: nil, **options, &block)
-      data = options.delete(:data) || {}
-
-      if part
-        data[:"#{component}-part"] = part
-      else
-        data[:component] = component
-        data[:variant] = variant if variant
-        data[:size] = size if size
-      end
-
-      options[:data] = data
-
-      content_tag(element, **options, &block)
-    end
-
-    # Renders a Kiso component partial.
+    # @example Render a badge
+    #   kui(:badge, color: :success, variant: :soft) { "Active" }
     #
-    #   kiso(:badge, variant: :success) { "Active" }
-    #   kiso(:card, :header) { ... }
-    #   kiso(:badge, collection: @statuses)
+    # @example Render a card sub-part
+    #   kui(:card, :header) { "Title" }
     #
-    def kiso(component, part = nil, collection: nil, **kwargs, &block)
+    # @example Render a collection
+    #   kui(:badge, collection: @tags)
+    def kui(component, part = nil, collection: nil, **kwargs, &block)
       path = if part
         "kiso/components/#{component}/#{part}"
       else
@@ -38,10 +31,36 @@ module Kiso
       end
 
       if collection
-        render partial: path, collection: collection, **kwargs, &block
+        render partial: path, collection: collection, locals: kwargs, &block
       else
         render path, **kwargs, &block
       end
     end
+
+    # Prepares +component_options+ for use with +content_tag+.
+    #
+    # Sets +data-slot+ for component identity (shadcn v4 convention) and
+    # merges any additional data attributes. Raises if +class:+ is passed
+    # (use +css_classes:+ instead).
+    #
+    # @param component_options [Hash] the +**component_options+ splat from the partial.
+    #   Any +data:+ key is extracted and merged with +slot+ and +data_attrs+.
+    # @param slot [String] the +data-slot+ value (kebab-case, e.g. +"card-header"+)
+    # @param data_attrs [Hash] additional data attributes (e.g. +controller: "kiso--toggle"+)
+    # @return [Hash] merged data attributes hash for +content_tag+
+    # @raise [ArgumentError] if +component_options+ contains a +class:+ key
+    #
+    # @example In a component partial
+    #   data: kiso_prepare_options(component_options, slot: "badge")
+    #
+    # @example With a Stimulus controller
+    #   data: kiso_prepare_options(component_options, slot: "toggle", controller: "kiso--toggle")
+    def kiso_prepare_options(component_options, slot:, **data_attrs)
+      if component_options.key?(:class)
+        raise ArgumentError, "Use css_classes: instead of class: for Kiso components"
+      end
+
+      (component_options.delete(:data) || {}).merge(slot: slot, **data_attrs)
+    end
   end
 end

data/app/helpers/kiso/icon_helper.rb

@@ -3,7 +3,13 @@
 require "tailwind_merge"
 
 module Kiso
+  # View helpers for rendering inline SVG icons.
+  #
+  # Included in all views automatically by {Engine}.
+  # Delegates to +kiso_icon_tag+ (provided by the kiso-icons gem) for
+  # actual SVG rendering.
   module IconHelper
+    # @return [Hash{Symbol => String}] maps size presets to Tailwind size utilities
     SIZE_PRESETS = {
       xs: "size-3",
       sm: "size-4",
@@ -12,23 +18,56 @@ module Kiso
       xl: "size-8"
     }.freeze
 
+    # @return [String] base Tailwind classes applied to every icon
     BASE_CLASSES = "shrink-0"
 
+    # Renders a configurable component icon.
+    #
+    # Components call this instead of {#kiso_icon} when the icon name should
+    # be overridable by host apps via {Configuration#icons Kiso.config.icons}.
+    #
+    # @param semantic_name [Symbol] a key from {Configuration#icons}
+    #   (e.g. +:chevron_right+, +:check+, +:x+)
+    # @param options [Hash] forwarded to {#kiso_icon}
+    # @return [ActiveSupport::SafeBuffer] rendered SVG
+    # @raise [KeyError] if +semantic_name+ is not registered
+    #
+    # @example
+    #   kiso_component_icon(:chevron_right, class: "size-3.5")
+    #   kiso_component_icon(:ellipsis, size: :sm)
+    def kiso_component_icon(semantic_name, **)
+      icon_name = Kiso.config.icons.fetch(semantic_name) {
+        raise KeyError, "Unknown Kiso icon: #{semantic_name.inspect}. " \
+          "Known icons: #{Kiso.config.icons.keys.join(", ")}"
+      }
+      kiso_icon(icon_name, **)
+    end
+
     # Renders an inline SVG icon with Tailwind classes.
     #
-    #   kiso_icon("lucide:check")
-    #   kiso_icon("check")                          # uses default set (lucide)
-    #   kiso_icon("check", size: :md)               # size preset (standalone use)
-    #   kiso_icon("check", class: "text-success")   # extra classes
-    #   kiso_icon("check", aria: { label: "Done" }) # accessible icon
+    # Size defaults to +nil+ so parent components (Button, Alert, Badge) can
+    # control icon sizing via CSS selectors like +[&_svg]:size-4+.
+    # Pass an explicit +size:+ for standalone icons outside components.
     #
-    # Size defaults to nil so parent components (Button, Alert, Badge) can
-    # control icon sizing via CSS selectors like [&_svg]:size-4.
-    # Pass an explicit size: for standalone icons outside components.
+    # @param name [String] icon identifier, optionally prefixed with set
+    #   (e.g. +"check"+, +"lucide:check"+)
+    # @param size [Symbol, nil] size preset from {SIZE_PRESETS}
+    #   (+:xs+, +:sm+, +:md+, +:lg+, +:xl+)
+    # @param options [Hash] forwarded to +kiso_icon_tag+
+    #   (e.g. +class:+, +aria:+, +data:+)
+    # @return [ActiveSupport::SafeBuffer] rendered SVG
     #
+    # @example Basic usage
+    #   kiso_icon("check")
+    # @example With size preset
+    #   kiso_icon("check", size: :md)
+    # @example With extra classes
+    #   kiso_icon("check", class: "text-success")
+    # @example Accessible icon
+    #   kiso_icon("check", aria: { label: "Done" })
     def kiso_icon(name, size: nil, **options)
       css_classes = options.delete(:class) || ""
-      size_class = size ? SIZE_PRESETS.fetch(size, nil) : nil
+      size_class = size ? SIZE_PRESETS.fetch(size) : nil
       merged = merge_icon_classes(BASE_CLASSES, size_class, css_classes)
 
       kiso_icon_tag(name, class: merged, **options)
@@ -36,11 +75,16 @@ module Kiso
 
     private
 
+    # Merges icon class parts via TailwindMerge, filtering out blanks.
+    #
+    # @param parts [Array<String, nil>] class strings to merge
+    # @return [String] deduplicated class string
     def merge_icon_classes(*parts)
       combined = parts.reject { |p| p.nil? || p.to_s.empty? }.join(" ")
       icon_class_merger.merge(combined)
     end
 
+    # @return [TailwindMerge::Merger] memoized merger instance
     def icon_class_merger
       @icon_class_merger ||= TailwindMerge::Merger.new
     end

data/app/helpers/kiso/theme_helper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kiso
+  # View helper for dark mode FOUC prevention.
+  #
+  # Included in all views automatically by {Engine}.
+  module ThemeHelper
+    THEME_SCRIPT = <<~JS.squish.freeze
+      (function(){
+        var k="theme";
+        var t=localStorage.getItem(k);
+        if(!t){var m=document.cookie.match(new RegExp("(?:^|; )"+k+"=([^;]*)"));t=m&&m[1]}
+        if(t==="dark"||((!t||t==="system")&&matchMedia("(prefers-color-scheme:dark)").matches)){
+          document.documentElement.classList.add("dark")
+        }
+      })()
+    JS
+
+    # Outputs an inline script that prevents dark mode FOUC.
+    #
+    # Reads the theme preference from localStorage (primary) or cookie
+    # (fallback), respects +prefers-color-scheme+ as default, and sets
+    # +.dark+ on +<html>+ synchronously before first paint.
+    #
+    # Call in +<head>+, ideally before stylesheet links.
+    #
+    # @example In a layout
+    #   <head>
+    #     <%= kiso_theme_script %>
+    #     <%= stylesheet_link_tag "tailwind" %>
+    #   </head>
+    #
+    # @return [ActiveSupport::SafeBuffer]
+    def kiso_theme_script
+      javascript_tag(THEME_SCRIPT, nonce: true)
+    end
+  end
+end