kanso 0.1.0

data/app/components/kanso/button_component.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Kanso
+  class ButtonComponent < ViewComponent::Base
+    include Kanso::ClassCombinable
+
+    THEME_CLASSES = {
+      primary: "bg-indigo-500 text-white hover:bg-indigo-600 active:bg-indigo-700",
+      danger:  "bg-red-600 text-white hover:bg-red-700 active:bg-red-800",
+      default: "bg-white text-indigo-600 border border-indigo-600 focus:ring-indigo-500/50 hover:bg-indigo-50 hover:border-indigo-700 active:bg-indigo-700 active:text-white"
+    }.freeze
+
+    def initialize(theme: :default, tag: :button, url: nil, method: nil, **options)
+      @theme = theme
+      @tag = tag
+      @url = url
+      @method = method
+      @options = options
+    end
+
+    def call
+      if @url
+        button_to(@url, method: @method, **html_options) do
+          content
+        end
+      else
+        content_tag(@tag, content, html_options)
+      end
+    end
+
+    private
+
+    def html_options
+      final_options = @options.dup
+      user_provided_class_value = final_options.delete(:class)
+      combined_class_string = combine_classes(classes, user_provided_class_value)
+      final_options.deep_merge(class: combined_class_string)
+    end
+
+    def classes
+      [ base_classes, theme_classes ].join(" ")
+    end
+
+    def base_classes
+      "inline-flex items-center justify-center gap-x-2 " +
+      "w-full sm:w-auto rounded-full font-semibold whitespace-nowrap select-none no-underline text-center px-5 py-2 " +
+      "shadow-md " +
+      "transform transition duration-200 " +
+      "hover:cursor-pointer " +
+      "active:translate-y-px active:shadow-none " +
+      "disabled:cursor-not-allowed disabled:opacity-50"
+    end
+
+    def theme_classes
+      THEME_CLASSES.fetch(@theme, THEME_CLASSES[:default])
+    end
+  end
+end

data/app/components/kanso/class_combinable.rb

@@ -0,0 +1,25 @@
+module Kanso
+  module ClassCombinable
+    extend ActiveSupport::Concern
+
+    def combine_classes(component_classes_string, user_classes_value)
+      component_classes_array = component_classes_string.split(" ")
+
+      user_classes_array = clean_and_split_classes(user_classes_value)
+
+      (component_classes_array + user_classes_array).compact.uniq.join(" ")
+    end
+
+    private
+
+    def clean_and_split_classes(value)
+      if value.nil?
+        []
+      elsif value.kind_of?(Array)
+        value
+      else
+        value.split(" ")
+      end
+    end
+  end
+end

data/app/components/kanso/dropdown_component.html.erb

@@ -0,0 +1,19 @@
+<div data-controller="kanso--dropdown" class="relative inline-block text-left">
+  <div data-action="click->kanso--dropdown#toggle">
+    <%= trigger %>
+  </div>
+
+  <div data-kanso--dropdown-target="panel"
+       class="hidden absolute right-0 z-10 mt-2 w-56 origin-top-right rounded-md bg-white shadow-lg ring-1 ring-black ring-opacity-5 focus:outline-none transition ease-out duration-100"
+       role="menu"
+       aria-orientation="vertical"
+       tabindex="-1"
+       data-action="
+         keydown.esc@window->kanso--dropdown#close
+         click@window->kanso--dropdown#closeOutside
+       ">
+
+    <%= content %>
+
+  </div>
+</div>

data/app/components/kanso/dropdown_component.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Kanso
+  class DropdownComponent < ViewComponent::Base
+    renders_one :trigger
+
+    def initialize
+    end
+  end
+end

data/app/components/kanso/form_field_component.html.erb

@@ -0,0 +1,24 @@
+<div data-controller="kanso--form" class="mb-4">
+  <%= form.label attribute, for: field_id, class: "block text-sm font-medium leading-6 text-slate-900" %>
+
+  <div class="relative mt-1">
+    <%= form.send(type, attribute, field_options) %>
+
+    <% if has_errors? %>
+      <div class="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-3">
+        <%= render Kanso::IconComponent.new(name: "exclamation-circle", class: "h-5 w-5 text-red-500") %>
+      </div>
+    <% end %>
+  </div>
+
+  <div id="<%= description_id %>" class="mt-2 text-sm min-h-[1.25rem]">
+    <% if has_errors? %>
+      <p data-kanso--form-target="errorMessage"
+         class="text-red-600 opacity-0 transition duration-300 ease-out -translate-y-2">
+        <%= form.object.errors.full_messages_for(attribute).to_sentence %>
+      </p>
+    <% elsif help_text.present? %>
+      <p class="text-slate-500"><%= help_text %></p>
+    <% end %>
+  </div>
+</div>

data/app/components/kanso/form_field_component.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Kanso
+  class FormFieldComponent < ViewComponent::Base
+    renders_one :help_text
+
+    attr_reader :form, :attribute, :type, :options
+
+    def initialize(form:, attribute:, type: :text_field, **options)
+      @form = form
+      @attribute = attribute
+      @type = type
+      @options = options
+    end
+
+    private
+
+    def has_errors?
+      form.object.errors.include?(attribute)
+    end
+
+    def field_id
+      helpers.dom_id(form.object, attribute)
+    end
+
+    def description_id
+      "#{field_id}_description"
+    end
+
+    def field_classes
+      base_classes = "block w-full rounded-md border-0 py-1.5 px-3 shadow-sm ring-1 ring-inset focus:ring-2 focus:ring-inset sm:text-sm sm:leading-6"
+
+      if has_errors?
+        error_classes = "text-red-900 ring-red-300 placeholder:text-red-300 focus:ring-red-500"
+        "#{base_classes} #{error_classes}"
+      else
+        normal_classes = "text-slate-900 ring-slate-300 placeholder:text-slate-400 focus:ring-blue-600"
+        "#{base_classes} #{normal_classes}"
+      end
+    end
+
+    def field_options
+      options.deep_merge(
+        id: field_id,
+        class: field_classes,
+        aria: { describedby: description_id },
+        data: { kanso__form_target: ("errorField" if has_errors?) }
+      )
+    end
+  end
+end

data/app/components/kanso/form_field_skeleton_component.html.erb

@@ -0,0 +1,7 @@
+<% fields.times do %>
+  <div class="mb-4 animate-pulse">
+    <div class="mb-1 h-5 w-1/3 rounded bg-slate-200"></div>
+    <div class="h-10 w-full rounded-md bg-slate-200"></div>
+    <div class="mt-2 h-5 w-3/4 rounded bg-slate-200"></div>
+  </div>
+<% end %>

data/app/components/kanso/form_field_skeleton_component.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kanso
+  class FormFieldSkeletonComponent < ViewComponent::Base
+    attr_reader :fields
+
+    def initialize(fields: 1)
+      @fields = fields
+    end
+  end
+end

data/app/components/kanso/icon_component.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kanso
+  class IconComponent < ViewComponent::Base
+    attr_reader :name, :options
+
+    def initialize(name:, **options)
+      @name = name
+      @options = options
+    end
+
+    def call
+      attributes = tag.attributes(
+        options.deep_merge(data: { icon_name: name })
+      )
+
+      raw_svg = cached_svg_content
+      raw_svg.sub("<svg", "<svg #{attributes}").html_safe
+    end
+
+    private
+
+    def cached_svg_content
+      Rails.cache.fetch("kanso:icon:#{name}", expires_in: 1.day) do
+        file_path = Kanso::Engine.root.join("app/assets/images/kanso/icons/#{name}.svg")
+        File.read(file_path) if File.exist?(file_path)
+      end.to_s
+    end
+  end
+end

data/app/components/kanso/modal_component.html.erb

@@ -0,0 +1,53 @@
+<div data-controller="kanso--modal">
+
+  <div data-action="click->kanso--modal#open">
+    <%= trigger %>
+  </div>
+
+  <div data-kanso--modal-target="container"
+      class="fixed inset-0 z-50 hidden"
+      data-action="keydown.esc@window->kanso--modal#close">
+
+    <div data-kanso--modal-target="backdrop"
+        data-action="mousedown->kanso--modal#backdropMousedown mouseup->kanso--modal#backdropMouseup"
+        class="fixed inset-0 flex w-full items-center justify-center bg-slate-900/70 p-4 transition-opacity duration-300 ease-in-out"
+        data-transition-enter-from="opacity-0"
+        data-transition-enter-to="opacity-100"
+        data-transition-leave-from="opacity-100"
+        data-transition-leave-to="opacity-0">
+
+      <div role="dialog"
+          aria-modal="true"
+          aria-labelledby="<%= header.title_id if header.present? %>"
+          data-kanso--modal-target="panel"
+          class="flex w-full <%= size_classes %> max-h-full transform flex-col rounded-lg bg-white text-left shadow-2xl transition-all duration-300 ease-in-out"
+          data-transition-enter-from="opacity-0 scale-95"
+          data-transition-enter-to="opacity-100 scale-100"
+          data-transition-leave-from="opacity-100 scale-100"
+          data-transition-leave-to="opacity-0 scale-95">
+
+        <% if header.present? %>
+          <div data-test-id="kanso--modal-header" class="flex flex-shrink-0 items-center justify-between rounded-t-lg border-b border-slate-200 p-4">
+            <h2 id="<%= header.title_id %>" class="text-lg font-semibold text-slate-900">
+              <%= header.title %>
+            </h2>
+            <button type="button" data-action="click->kanso--modal#close" class="-m-2 p-2 text-slate-400 hover:cursor-pointer hover:text-slate-600">
+              <span class="sr-only">Close</span>
+              <%= render Kanso::IconComponent.new(name: "x-mark", class: "h-6 w-6") %>
+            </button>
+          </div>
+        <% end %>
+
+        <div data-test-id="kanso--modal-body" class="overflow-y-auto p-4">
+          <%= content %>
+        </div>
+
+        <% if footer.present? %>
+          <div data-test-id="kanso--modal-footer" class="flex flex-shrink-0 flex-row-reverse items-center gap-x-2 rounded-b-lg border-t border-slate-200 bg-slate-50 p-4">
+            <%= footer %>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>

data/app/components/kanso/modal_component.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Kanso
+  class ModalComponent < ViewComponent::Base
+    renders_one :trigger
+    renders_one :header, ->(title:) do
+      HeaderComponent.new(title: title)
+    end
+    renders_one :footer
+
+    attr_reader :size
+
+    def initialize(size: :lg)
+      @size = size
+    end
+
+    private
+
+    def size_classes
+      case size
+      when :sm
+        "max-w-sm"
+      when :md
+        "max-w-md"
+      when :lg
+        "max-w-lg"
+      when :xl
+        "max-w-xl"
+      when :xxl
+        "max-w-2xl"
+      else
+        "max-w-lg"
+      end
+    end
+
+    class HeaderComponent < ViewComponent::Base
+      attr_reader :title, :title_id
+
+      def initialize(title:)
+        @title = title
+        @title_id = "modal-title-#{SecureRandom.hex(4)}"
+      end
+
+      def call
+        content
+      end
+    end
+  end
+end

data/app/components/kanso/notification_component.html.erb

@@ -0,0 +1,25 @@
+<div data-controller="kanso--notification"
+     class="flex w-full max-w-sm items-center rounded-lg bg-white p-4 shadow-lg ring-1 ring-black ring-opacity-5 opacity-0 transform translate-x-full transition-all duration-300 ease-out"
+     role="<%= theme_data.aria_role %>">
+  <div class="flex-shrink-0">
+    <div class="flex h-8 w-8 items-center justify-center rounded-full <%= theme_data.icon_bg_classes %>">
+      <%= render Kanso::IconComponent.new(name: theme_data.icon_name, class: "h-5 w-5 #{theme_data.icon_color_classes}") %>
+    </div>
+  </div>
+  <div class="ml-3 w-0 flex-1 pt-0.5">
+    <% if title.present? %>
+      <h3 class="text-sm font-medium <%= theme_data.title_text_classes %>"><%= title %></h3>
+      <p class="mt-1 text-sm <%= theme_data.body_text_classes %>"><%= message %></p>
+    <% else %>
+      <p class="text-sm font-medium <%= theme_data.title_text_classes %>"><%= message %></p>
+    <% end %>
+  </div>
+  <div class="ml-4 flex flex-shrink-0">
+    <button type="button"
+            data-action="click->kanso--notification#close"
+            class="inline-flex rounded-md bg-white text-gray-400 transition-colors hover:text-gray-500 hover:cursor-pointer focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">
+      <span class="sr-only">Close</span>
+      <%= render Kanso::IconComponent.new(name: "x-mark", class: "h-5 w-5") %>
+    </button>
+  </div>
+</div>

data/app/components/kanso/notification_component.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Kanso
+  class NotificationComponent < ViewComponent::Base
+    Theme = Struct.new(
+      :icon_name,
+      :icon_bg_classes,
+      :icon_color_classes,
+      :title_text_classes,
+      :body_text_classes,
+      :aria_role,
+      keyword_init: true
+    )
+
+    THEMES = {
+      success: Theme.new(
+        icon_name: "check-circle",
+        icon_bg_classes: "bg-green-100",
+        icon_color_classes: "text-green-600",
+        title_text_classes: "text-green-800",
+        body_text_classes: "text-green-700",
+        aria_role: "status"
+      ),
+      error: Theme.new(
+        icon_name: "x-circle",
+        icon_bg_classes: "bg-red-100",
+        icon_color_classes: "text-red-600",
+        title_text_classes: "text-red-800",
+        body_text_classes: "text-red-700",
+        aria_role: "alert"
+      ),
+      warning: Theme.new(
+        icon_name: "exclamation-triangle",
+        icon_bg_classes: "bg-yellow-100",
+        icon_color_classes: "text-yellow-600",
+        title_text_classes: "text-yellow-800",
+        body_text_classes: "text-yellow-700",
+        aria_role: "alert"
+      ),
+      info: Theme.new(
+        icon_name: "information-circle",
+        icon_bg_classes: "bg-blue-100",
+        icon_color_classes: "text-blue-600",
+        title_text_classes: "text-blue-800",
+        body_text_classes: "text-blue-700",
+        aria_role: "status"
+      )
+    }.freeze
+
+    attr_reader :title, :message, :theme_data
+
+    def initialize(message:, title: nil, theme: :info)
+      @title = title
+      @message = message
+      @theme_data = THEMES[theme.to_sym] || THEMES[:info]
+    end
+  end
+end

data/app/controllers/kanso/application_controller.rb

@@ -0,0 +1,4 @@
+module Kanso
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/kanso/application_helper.rb

@@ -0,0 +1,4 @@
+module Kanso
+  module ApplicationHelper
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,5 @@
+pin "controllers/kanso--modal_controller", to: "kanso/controllers/modal_controller.js"
+pin "controllers/kanso--form_controller", to: "kanso/controllers/form_controller.js"
+pin "controllers/kanso--notification_controller", to: "kanso/controllers/notification_controller.js"
+pin "controllers/kanso--dropdown_controller", to: "kanso/controllers/dropdown_controller.js"
+pin "transition", to: "kanso/helpers/transition.js"

data/config/routes.rb

@@ -0,0 +1,2 @@
+Kanso::Engine.routes.draw do
+end

data/lib/generators/kanso/install/install_generator.rb

@@ -0,0 +1,209 @@
+# lib/generators/kanso/install/install_generator.rb
+
+class Kanso::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  # Kanso Philosophy: Public methods are generator tasks.
+  # Helper methods must be explicitly declared to avoid being run by Thor.
+  no_commands do
+    # This method exists to make the generator testable.
+    # In a test environment, we can stub this to point to a temporary directory.
+    def application_root
+      Rails.root
+    end
+  end
+
+  def install
+    say "Kanso: Starting installation...", :cyan
+
+    # --- Prerequisite Checks based on observable facts ---
+    css_path = application_root.join("app/assets/tailwind/application.css")
+    root_config_path = application_root.join("tailwind.config.js")
+    legacy_config_path = application_root.join("config/tailwind.config.js")
+
+    unless File.exist?(css_path)
+      say "\nKanso Installation Blocked", :red
+      say "--------------------------", :red
+      say "Could not find the required Tailwind CSS entrypoint at:", :yellow
+      say "`app/assets/tailwind/application.css`", :bold
+      say "\nThis file is required for Kanso to be installed correctly.", :yellow
+      say "Please run `rails tailwindcss:install` to generate it, then re-run this generator.", :cyan
+      return
+    end
+
+    if File.exist?(legacy_config_path)
+      say "\nKanso Installation Blocked", :red
+      say "--------------------------", :red
+      say "A Tailwind configuration file was found at:", :yellow
+      say "`config/tailwind.config.js`", :bold
+      say "\nTo ensure a single source of truth, Kanso requires the configuration to be at the project root.", :yellow
+      say "Please migrate this file to `tailwind.config.js` at the root of your project, then re-run this generator.", :cyan
+      return
+    end
+
+    # --- Core Logic ---
+    configure_tailwind_config(root_config_path)
+    configure_application_css(css_path, root_config_path)
+
+    say "Kanso: Installation complete! ✨", :green
+  end
+
+  private
+
+  # --- Tailwind Configuration Logic ---
+
+  def configure_tailwind_config(path)
+    if File.exist?(path)
+      inject_into_tailwind_config(path)
+    else
+      create_tailwind_config(path)
+    end
+  end
+
+  def inject_into_tailwind_config(path)
+    file_content = File.read(path)
+
+    if file_content.include?("// Kanso: Managed")
+      say "Kanso: Tailwind configuration is already Kanso-aware. Skipping.", :yellow
+      return
+    end
+
+    if file_content.match?(/export\s+default/m)
+      say "Kanso: Your `tailwind.config.js` uses ESM syntax (`export default`).", :yellow
+      say "       To prevent conflicts, Kanso will not modify this file.", :yellow
+      say "       Please manually add the Kanso content path to your config:", :cyan
+      say "       You'll need `path.join` and this helper function:", :bold
+      puts find_kanso_gem_path_function.indent(7)
+      puts "       And add this to your `content` array:".indent(7)
+      puts "       `path.join(kansoGemPath, \"app/components/**/*.{rb,html.erb}\")`".indent(7)
+      return
+    end
+
+    say "Kanso: Found existing `tailwind.config.js`. Safely appending Kanso configuration.", :cyan
+    append_to_file path, kanso_scriptlet
+  end
+
+  def create_tailwind_config(path)
+    say "Kanso: No `tailwind.config.js` found. Creating a new, Kanso-aware configuration.", :cyan
+    create_file path, <<~JS
+      // Kanso: Managed Tailwind Configuration
+      const path = require("path");
+      const { execSync } = require("child_process");
+
+      #{find_kanso_gem_path_function.strip.indent(2)}
+
+      const kansoGemPath = findKansoGemPath();
+
+      module.exports = {
+        content: [
+          "./app/helpers/**/*.rb",
+          "./app/javascript/**/*.js",
+          "./app/views/**/*.{html,html.erb,erb}",
+          path.join(kansoGemPath, "app/components/**/*.{rb,html.erb}")
+        ],
+        theme: {
+          extend: {},
+        },
+        plugins: [],
+      }
+    JS
+  end
+
+  # --- CSS Configuration Logic ---
+
+  def configure_application_css(css_path, config_path)
+    file_content = File.read(css_path)
+    inject_config_bridge(css_path, file_content, config_path)
+    inject_base_styles(css_path, file_content)
+  end
+
+  def inject_config_bridge(css_path, file_content, config_path)
+    if file_content.include?("@config")
+      say "Kanso: `@config` directive already present in CSS. Skipping.", :yellow
+    else
+      relative_config_path = config_path.relative_path_from(css_path.dirname).to_s
+      config_block = "/* Kanso: Tells Tailwind to use our smart JS config */\n@config \"#{relative_config_path}\";\n\n"
+      prepend_to_file css_path, config_block
+      say "Kanso: Injected `@config` bridge into `#{relative_path(css_path)}`.", :green
+    end
+  end
+
+  def inject_base_styles(css_path, file_content)
+    if file_content.include?("/* Kanso: Base Styles")
+      say "Kanso: Base styles already present. Skipping.", :yellow
+    else
+      anchor = /@import\s+["']tailwindcss["'];\s*(\r\n|\n)/
+      if file_content.match?(anchor)
+        insert_into_file css_path, "\n#{base_styles_block.strip}\n", after: anchor
+        say "Kanso: Injected base styles.", :green
+      else
+        say "Kanso: Could not find the `@import \"tailwindcss\";` directive.", :red
+        say "         Please add the Kanso base styles block manually:", :yellow
+        puts base_styles_block
+      end
+    end
+  end
+
+  # --- Helper Methods & Content Blocks ---
+
+  def kanso_scriptlet
+    <<~JS
+
+      // --- Kanso Configuration (appended by `rails g kanso:install`) ---
+      // Kanso: Managed
+      try {
+        const kansoGemPath = require("child_process").execSync(`bundle exec ruby -e "puts Bundler.rubygems.find_name(%q{kanso}).first.full_gem_path"`).toString().trim();
+        if (kansoGemPath) {
+          const kansoContentPath = require("path").join(kansoGemPath, "app/components/**/*.{rb,html.erb}");
+          if (module.exports.content) {
+            if (!module.exports.content.includes(kansoContentPath)) {
+              module.exports.content.push(kansoContentPath);
+            }
+          } else {
+            module.exports.content = [kansoContentPath];
+          }
+        }
+      } catch (e) {
+        console.error("Kanso post-install configuration failed. Please add the Kanso content path to your tailwind.config.js manually.");
+        console.error(e);
+      }
+      // --- End Kanso Configuration ---
+    JS
+  end
+
+  def find_kanso_gem_path_function
+    <<~JS
+      function findKansoGemPath() {
+        try {
+          return execSync(
+            `bundle exec ruby -e "puts Bundler.rubygems.find_name(%q{kanso}).first.full_gem_path"`
+          ).toString().trim();
+        } catch (e) {
+          console.error("Could not find the 'kanso' gem via Bundler. Please ensure it's in your Gemfile.");
+          console.error(e.stderr.toString());
+          process.exit(1);
+        }
+      }
+    JS
+  end
+
+  def base_styles_block
+    <<~CSS
+      /* Kanso: Base Styles injected into the native 'base' cascade layer */
+      @layer base {
+        input:focus, textarea:focus, select:focus {
+          outline: none;
+        }
+        turbo-frame[busy] {
+          opacity: 0.5;
+          transition: opacity 0.3s ease-in-out;
+        }
+      }
+      /* End Kanso Base Styles */
+    CSS
+  end
+
+  def relative_path(path)
+    path.relative_path_from(Rails.root).to_s
+  end
+end

data/lib/kanso/engine.rb

@@ -0,0 +1,11 @@
+require "view_component"
+
+module Kanso
+  class Engine < ::Rails::Engine
+    isolate_namespace Kanso
+
+    initializer "kanso.importmap", before: "importmap" do |app|
+      app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+    end
+  end
+end