keystone_ui 0.6.0

data/app/helpers/keystone_ui_helper.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module KeystoneUiHelper
+  def ui_accordion(**args)
+    render Keystone::Ui::AccordionComponent.new(**args)
+  end
+
+  def ui_tab_switcher(**args, &block)
+    render Keystone::Ui::TabSwitcherComponent.new(**args), &block
+  end
+
+  def ui_stat_card(**args)
+    render Keystone::Ui::StatCardComponent.new(**args)
+  end
+
+  def ui_chart_card(**args, &block)
+    render Keystone::Ui::ChartCardComponent.new(**args), &block
+  end
+
+  def ui_line_chart(**args)
+    render Keystone::Ui::LineChartComponent.new(**args)
+  end
+
+  def ui_cta_banner(**args, &block)
+    render Keystone::Ui::CtaBannerComponent.new(**args), &block
+  end
+
+  def ui_feature_grid(**args)
+    render Keystone::Ui::FeatureGridComponent.new(**args)
+  end
+
+  def ui_hero(**args, &block)
+    render Keystone::Ui::HeroComponent.new(**args), &block
+  end
+
+  def ui_modal(**args, &block)
+    render Keystone::Ui::ModalComponent.new(**args), &block
+  end
+
+  def ui_badge(**args)
+    render Keystone::Ui::BadgeComponent.new(**args)
+  end
+
+  def ui_copy_button(**args)
+    render Keystone::Ui::CopyButtonComponent.new(**args)
+  end
+
+  def ui_card(**args)
+    render Keystone::Ui::CardComponent.new(**args)
+  end
+
+  def ui_button(**args)
+    render Keystone::Ui::ButtonComponent.new(**args)
+  end
+
+  def ui_data_table(**args, &block)
+    render Keystone::Ui::DataTableComponent.new(**args), &block
+  end
+
+  def ui_page(**args, &block)
+    render Keystone::Ui::PageComponent.new(**args), &block
+  end
+
+  def ui_section(**args, &block)
+    render Keystone::Ui::SectionComponent.new(**args), &block
+  end
+
+  def ui_grid(**args, &block)
+    render Keystone::Ui::GridComponent.new(**args), &block
+  end
+
+  def ui_panel(**args, &block)
+    render Keystone::Ui::PanelComponent.new(**args), &block
+  end
+
+  def ui_card_link(**args, &block)
+    render Keystone::Ui::CardLinkComponent.new(**args), &block
+  end
+
+  def ui_input(**args)
+    render Keystone::Ui::InputComponent.new(**args)
+  end
+
+  def ui_textarea(**args)
+    render Keystone::Ui::TextareaComponent.new(**args)
+  end
+
+  def ui_select(**args)
+    render Keystone::Ui::SelectComponent.new(**args)
+  end
+
+  def ui_form_field(**args)
+    render Keystone::Ui::FormFieldComponent.new(**args)
+  end
+
+  def ui_page_header(**args, &block)
+    render Keystone::Ui::PageHeaderComponent.new(**args), &block
+  end
+
+  def ui_alert(**args)
+    render Keystone::Ui::AlertComponent.new(**args)
+  end
+
+  def ui_form_page(**args)
+    render Keystone::Ui::FormPageComponent.new(**args)
+  end
+
+  def ui_show_page(**args)
+    render Keystone::Ui::ShowPageComponent.new(**args)
+  end
+
+  def ui_mobile_header(**args)
+    render Keystone::Ui::MobileHeaderComponent.new(**args)
+  end
+
+  def ui_mobile_actions(**args, &block)
+    render Keystone::Ui::MobileActionsComponent.new(**args), &block
+  end
+
+  def ui_navbar(**args, &block)
+    render Keystone::Ui::NavbarComponent.new(**args), &block
+  end
+
+  def ui_nav_item(**args)
+    render Keystone::Ui::NavItemComponent.new(**args)
+  end
+
+  def ui_nav_dropdown(**args, &block)
+    render Keystone::Ui::NavDropdownComponent.new(**args), &block
+  end
+
+  def ui_bottom_nav(**args, &block)
+    render Keystone::Ui::BottomNavComponent.new(**args), &block
+  end
+
+  def ui_bottom_nav_item(**args)
+    render Keystone::Ui::BottomNavItemComponent.new(**args)
+  end
+
+  def ui_option_card(**args, &block)
+    render Keystone::Ui::OptionCardComponent.new(**args), &block
+  end
+
+  def ui_radio_card(**args)
+    render Keystone::Ui::RadioCardComponent.new(**args)
+  end
+
+  def ui_progress(**args)
+    render Keystone::Ui::ProgressComponent.new(**args)
+  end
+
+  def ui_settings_link(**args)
+    render Keystone::Ui::SettingsLinkComponent.new(**args)
+  end
+
+  def ui_color_picker(**args)
+    render Keystone::Ui::ColorPickerComponent.new(**args)
+  end
+
+  def ui_multi_select(**args)
+    render Keystone::Ui::MultiSelectComponent.new(**args)
+  end
+
+  def ui_swipe_deck(**args, &block)
+    render Keystone::Ui::SwipeDeckComponent.new(**args), &block
+  end
+
+  def ui_column_picker(**args)
+    render Keystone::Ui::ColumnPickerComponent.new(**args)
+  end
+
+  def ui_form(**args, &block)
+    render Keystone::Ui::FormComponent.new(**args), &block
+  end
+
+  def ui_file_upload(**args)
+    render Keystone::Ui::FileUploadComponent.new(**args)
+  end
+
+  def ui_funnel(**args)
+    render Keystone::Ui::FunnelComponent.new(**args)
+  end
+
+  def ui_pipeline(**args)
+    render Keystone::Ui::PipelineComponent.new(**args)
+  end
+
+  def ui_code(**args, &block)
+    render Keystone::Ui::CodeComponent.new(**args), &block
+  end
+
+  def ui_disclosure(**args, &block)
+    render Keystone::Ui::DisclosureComponent.new(**args), &block
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,19 @@
+pin "keystone_ui/index", to: "keystone_ui/index.js"
+pin "keystone_ui/color_picker_controller", to: "keystone_ui/color_picker_controller.js"
+pin "keystone_ui/multi_select_controller", to: "keystone_ui/multi_select_controller.js"
+pin "keystone_ui/swipe_deck_controller", to: "keystone_ui/swipe_deck_controller.js"
+pin "keystone_ui/column_picker_controller", to: "keystone_ui/column_picker_controller.js"
+pin "keystone_ui/file_upload_controller", to: "keystone_ui/file_upload_controller.js"
+pin "keystone_ui/dropdown_controller", to: "keystone_ui/dropdown_controller.js"
+pin "keystone_ui/dismiss_controller", to: "keystone_ui/dismiss_controller.js"
+pin "keystone_ui/modal_controller", to: "keystone_ui/modal_controller.js"
+pin "keystone_ui/clipboard_controller", to: "keystone_ui/clipboard_controller.js"
+pin "keystone_ui/tab_switcher_controller", to: "keystone_ui/tab_switcher_controller.js"
+pin "keystone_ui/accordion_controller", to: "keystone_ui/accordion_controller.js"
+pin "keystone_ui/stat_card_info_controller", to: "keystone_ui/stat_card_info_controller.js"
+pin "keystone_ui/auto_submit_controller", to: "keystone_ui/auto_submit_controller.js"
+pin "keystone_ui/line_chart_controller", to: "keystone_ui/line_chart_controller.js"
+
+# Chart.js for the line-chart controller, so host apps don't pin it themselves.
+# Vendored as a single self-contained bundle (deps inlined, no external imports).
+pin "chart.js", to: "keystone_ui/chartjs.js"

data/lib/generators/keystone/install_generator.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Keystone
+  class InstallGenerator < Rails::Generators::Base
+    desc "Set up Keystone UI in your Rails application"
+
+    TAILWIND_IMPORT = '@import "tailwindcss";'
+    KEYSTONE_IMPORT = '@import "./keystone_source.css";'
+
+    JS_CONTROLLERS_PATH = "app/javascript/controllers/index.js"
+    JS_IMPORT = 'import { registerControllers } from "keystone_ui/index"'
+    JS_REGISTER = "registerControllers(application)"
+
+    def setup_tailwind
+      say ""
+      say "Keystone UI — setup", :green
+      say "=" * 40
+      say ""
+
+      css_path = Rails.root.join("app/assets/tailwind/application.css")
+      unless css_path.exist?
+        FileUtils.mkdir_p(css_path.dirname)
+        File.write(css_path, "#{TAILWIND_IMPORT}\n#{KEYSTONE_IMPORT}\n")
+        say "  ✔ Created application.css with Tailwind and Keystone imports", :green
+        say ""
+        say "Done! See the README for component usage.", :green
+        return
+      end
+
+      content = css_path.read
+      changed = false
+
+      # Remove legacy @import for engine CSS (no longer needed)
+      legacy_import = '@import "../builds/tailwind/keystone_components_engine";' # also handles pre-rename installs
+      if content.include?(legacy_import)
+        gsub_file css_path, /#{Regexp.escape(legacy_import)}\n?/, ""
+        say "  ✔ Removed legacy engine CSS import", :green
+        changed = true
+      end
+
+      # Remove legacy inline safelist (replaced by @source path injection)
+      legacy_safelist = "/* keystone:safelist */"
+      if content.include?(legacy_safelist)
+        gsub_file css_path, /#{Regexp.escape(legacy_safelist)}.*\n?/, ""
+        say "  ✔ Removed legacy inline safelist", :green
+        changed = true
+      end
+
+      # Remove legacy marker comment (replaced by @import for keystone_source.css)
+      legacy_marker = "/* keystone:source */"
+      content = css_path.read # re-read after removals
+      if content.include?(legacy_marker)
+        gsub_file css_path, /#{Regexp.escape(legacy_marker)}.*\n?/, ""
+        say "  ✔ Removed legacy source marker", :green
+        changed = true
+      end
+
+      # Inject @import for keystone_source.css (written at boot by engine initializer)
+      content = css_path.read # re-read after removals
+      unless content.include?(KEYSTONE_IMPORT)
+        inject_into_file css_path, "#{KEYSTONE_IMPORT}\n", after: /#{Regexp.escape(TAILWIND_IMPORT)}\n/
+        say "  ✔ Added Keystone source import", :green
+        changed = true
+      end
+
+      say "  ✔ application.css already up to date", :green unless changed
+      say ""
+      say "Done! See the README for component usage.", :green
+    end
+
+    def setup_javascript
+      say ""
+      say "Wiring Keystone UI Stimulus controllers...", :green
+
+      js_path = Rails.root.join(JS_CONTROLLERS_PATH)
+      unless js_path.exist?
+        say "  ⚠ #{JS_CONTROLLERS_PATH} not found — add `#{JS_REGISTER}` to your Stimulus setup manually.", :yellow
+        return
+      end
+
+      if js_path.read.include?(JS_REGISTER)
+        say "  ✔ Keystone UI controllers already registered", :green
+        return
+      end
+
+      append_to_file js_path, "\n#{JS_IMPORT}\n#{JS_REGISTER}\n"
+      say "  ✔ Registered Keystone UI controllers", :green
+    end
+  end
+end

data/lib/keystone_ui/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class Configuration
+    attr_accessor :accent, :surface
+
+    def initialize
+      @accent = :blue
+      @surface = :zinc
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/keystone_ui/engine.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class Engine < ::Rails::Engine
+    config.autoload_paths << root.join("app/components")
+
+    # Pin JavaScript controllers for importmap-based host apps.
+    initializer "keystone_ui.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+      end
+    end
+
+    # Write a separate keystone_source.css with the gem's @source directive
+    # so Tailwind can scan component files during asset compilation.
+    #
+    # Uses after_initialize so host app config/initializers (where
+    # KeystoneUi.configure is called) have already run. Dependent engines
+    # that also need the palette should use config.after_initialize too —
+    # Rails runs these in engine dependency order, so KeystoneUi's block
+    # executes before any engine that depends on it.
+    config.after_initialize do
+      tailwind_dir = Rails.root.join("app/assets/tailwind")
+      css_path = tailwind_dir.join("application.css")
+      next unless css_path.exist?
+
+      keystone_import = '@import "./keystone_source.css";'
+      next unless css_path.read.include?(keystone_import)
+
+      source_css = tailwind_dir.join("keystone_source.css")
+      lines = [ %(@source "#{root}/app/components/**/*.{erb,rb}";) ]
+
+      # Import theme CSS (accent + surface custom property defaults)
+      theme_css = root.join("app/assets/tailwind/keystone_ui_engine/theme.css")
+      lines << %(@import "#{theme_css}";) if theme_css.exist?
+
+      # Import component CSS files shipped with the gem
+      nav_css = root.join("app/assets/tailwind/keystone_ui_engine/nav.css")
+      lines << %(@import "#{nav_css}";) if nav_css.exist?
+
+      color_picker_css = root.join("app/assets/tailwind/keystone_ui_engine/color_picker.css")
+      lines << %(@import "#{color_picker_css}";) if color_picker_css.exist?
+
+      source_css.write(lines.join("\n") + "\n")
+    end
+  end
+end

data/lib/keystone_ui/safelist.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Safelist
+    # All component classes to scan for Tailwind CSS classes.
+    # The safelist_spec verifies this list matches Keystone::Ui components.
+    COMPONENTS = [
+      Keystone::Ui::AccordionComponent,
+      Keystone::Ui::TabSwitcherComponent,
+      Keystone::Ui::StatCardComponent,
+      Keystone::Ui::ChartCardComponent,
+      Keystone::Ui::LineChartComponent,
+      Keystone::Ui::CtaBannerComponent,
+      Keystone::Ui::FeatureGridComponent,
+      Keystone::Ui::HeroComponent,
+      Keystone::Ui::ModalComponent,
+      Keystone::Ui::SelectComponent,
+      Keystone::Ui::BadgeComponent,
+      Keystone::Ui::CopyButtonComponent,
+      Keystone::Ui::CardComponent,
+      Keystone::Ui::ButtonComponent,
+      Keystone::Ui::DataTableComponent,
+      Keystone::Ui::PageComponent,
+      Keystone::Ui::SectionComponent,
+      Keystone::Ui::GridComponent,
+      Keystone::Ui::PanelComponent,
+      Keystone::Ui::CardLinkComponent,
+      Keystone::Ui::InputComponent,
+      Keystone::Ui::TextareaComponent,
+      Keystone::Ui::FormFieldComponent,
+      Keystone::Ui::PageHeaderComponent,
+      Keystone::Ui::AlertComponent,
+      Keystone::Ui::NavDropdownComponent,
+      Keystone::Ui::NavItemComponent,
+      Keystone::Ui::BottomNavItemComponent,
+      Keystone::Ui::NavbarComponent,
+      Keystone::Ui::BottomNavComponent,
+      Keystone::Ui::SettingsLinkComponent,
+      Keystone::Ui::FormPageComponent,
+      Keystone::Ui::MobileActionsComponent,
+      Keystone::Ui::MobileHeaderComponent,
+      Keystone::Ui::ShowPageComponent,
+      Keystone::Ui::OptionCardComponent,
+      Keystone::Ui::RadioCardComponent,
+      Keystone::Ui::ProgressComponent,
+      Keystone::Ui::ColorPickerComponent,
+      Keystone::Ui::MultiSelectComponent,
+      Keystone::Ui::SwipeDeckComponent,
+      Keystone::Ui::ColumnPickerComponent,
+      Keystone::Ui::FormComponent,
+      Keystone::Ui::FileUploadComponent,
+      Keystone::Ui::FunnelComponent,
+      Keystone::Ui::PipelineComponent,
+      Keystone::Ui::CodeComponent,
+      Keystone::Ui::DisclosureComponent
+    ].freeze
+
+    # Constants that hold non-CSS values (e.g. HTML input type maps)
+    SKIP_CONSTANTS = %i[TYPE_MAP ELLIPSIS_ICON BACK_ICON CARET_ICON CLOSE_ICON COPY_ICON SORT_ASC_ICON SORT_DESC_ICON SORT_NEUTRAL_ICON COLUMNS_ICON UPLOAD_ICON].freeze
+
+    # Classes used in Ruby methods or ERB templates, not in frozen constants.
+    # These cannot be auto-extracted and must be listed manually.
+    # The safelist_spec ensures every entry here appears in SAFELIST.
+    NON_CONSTANT_CLASSES = %w[
+      grid
+      mx-auto
+      overflow-hidden rounded-lg border border-gray-200 shadow-sm
+      dark:border-zinc-700 dark:shadow-none
+      relative min-w-full divide-y divide-gray-300 dark:divide-white/15
+      bg-gray-50 dark:bg-gray-800/75
+      divide-gray-200 bg-white dark:divide-white/10 dark:bg-gray-800/50
+      px-3 py-4 text-sm text-gray-500 dark:text-gray-400
+    ].freeze
+
+    def self.extract_classes_from_hash(hash, classes)
+      hash.each_value do |v|
+        case v
+        when String then classes.concat(v.split)
+        when Hash then extract_classes_from_hash(v, classes)
+        end
+      end
+    end
+
+    def self.generate
+      classes = []
+
+      COMPONENTS.each do |klass|
+        klass.constants(false).each do |const_name|
+          next if SKIP_CONSTANTS.include?(const_name)
+
+          value = klass.const_get(const_name)
+          case value
+          when String then classes.concat(value.split)
+          when Hash then extract_classes_from_hash(value, classes)
+          end
+        end
+      end
+
+      classes.concat(NON_CONSTANT_CLASSES)
+
+      classes.uniq.sort.join(" ")
+    end
+  end
+
+  SAFELIST = Safelist.generate
+end

data/lib/keystone_ui/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  VERSION = "0.6.0"
+end

data/lib/keystone_ui.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "view_component"
+require "keystone_ui/configuration"
+require "keystone_ui/engine"
+require "keystone_ui/version"
+
+module KeystoneUi
+end