odt-ui-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7cfd3ce3bb87002fd436c806e91c5265f0e6c86ad6526d317e480d2fdc6fa833
+  data.tar.gz: f0e8f657c95a809ff669ab4bede5faca1175ceea322478cbd2d139700dcbe475
+SHA512:
+  metadata.gz: 2abe1004260233049d5a659e6efe5634167eb92f9704c9d33f74741215db957a55ba95d1c30ca4009389add9ebfb3bfc8e0ac062bbbebac36fe36988095c2cf4
+  data.tar.gz: 9beb448b7fe69848789ff861b29c57baa370cdd75dc365858a8c353bfc74457572c09b5450e7048be19be9c08561a593f00e98e74a724d29af4584335dc2a5a2

data/README.md

@@ -0,0 +1,75 @@
+# ODT UI Rails Integration (`odt-ui-rails`)
+
+Official Ruby on Rails integration for **ODT-Lightweight-UI**. Allows you to use React-based ODT design tokens and components seamlessly inside Rails MVC views (`.html.erb`) with zero boilerplate.
+
+---
+
+## Quick Start
+
+### 1. Add Gem to Rails `Gemfile`
+
+```ruby
+# From local monorepo / subfolder:
+gem "odt-ui-rails", path: "path/to/ODT-Lightweight-UI/integrations/rails"
+
+# Or from GitHub:
+# gem "odt-ui-rails", github: "PixxelTK/ODT-Lightweight-UI", glob: "integrations/rails/*.gemspec"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### 2. Run the Generator
+
+```bash
+bin/rails g odt:install
+```
+
+_This command will automatically install the npm dependencies, generate the Stimulus controller + component registry, and link the ODT stylesheets._
+
+---
+
+## Usage in ERB Views
+
+### Buttons
+
+```erb
+<%= odt_button "บันทึกข้อมูล", variant: "primary", size: "md" %>
+<%= odt_button "ยกเลิก", variant: "ghost", size: "md" %>
+```
+
+### Form Inputs
+
+```erb
+<%= form_with url: users_path do |f| %>
+  <%= odt_input :email, label: "อีเมล", placeholder: "user@odt.com", required: true %>
+  <%= odt_password_input :password, label: "รหัสผ่าน" %>
+  <%= odt_button "เข้าสู่ระบบ", variant: "primary", type: "submit" %>
+<% end %>
+```
+
+### Cards & Layouts
+
+```erb
+<%= odt_card title: "ภาพรวมสถิติ" do %>
+  <%= odt_stat_card title: "Total Users", value: "12,450", change: "+14.2%" %>
+<% end %>
+```
+
+### Generic Component Mounting
+
+```erb
+<%= odt_component :Badge, variant: "success", children: "Active" %>
+<%= odt_component :Avatar, src: "https://avatar.iran.liara.run/public", name: "John Doe" %>
+```
+
+---
+
+## How It Works Under the Hood
+
+1. **Rails Engine**: Automatically injects `OdtUi::Helper` methods into ActionView templates.
+2. **Stimulus Adapter (`odt_component_controller.js`)**: Safely mounts and unmounts React components in sync with Hotwire/Turbo navigation.
+3. **Registry (`odt_registry.js`)**: Maps string names to ODT React components. You can register custom app-specific wrappers here easily.

data/lib/generators/odt/install_generator.rb

@@ -0,0 +1,76 @@
+require "rails/generators/base"
+
+module Odt
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs ODT-Lightweight-UI dependencies, Stimulus controllers, and stylesheet imports into Rails"
+
+      def install_javascript_dependencies
+        say "Installing JS dependencies (odt-lightweight-ui, react, react-dom)...", :green
+
+        packages = "odt-lightweight-ui react react-dom @hotwired/stimulus"
+
+        if File.exist?("yarn.lock")
+          run "yarn add #{packages}"
+        elsif File.exist?("pnpm-lock.yaml")
+          run "pnpm add #{packages}"
+        elsif File.exist?("bun.lockb") || File.exist?("bun.lock")
+          run "bun add #{packages}"
+        elsif File.exist?("package.json")
+          run "npm install #{packages}"
+        else
+          say "No package.json detected. Please ensure your Rails JS bundler (esbuild, vite, or importmap) is configured.", :yellow
+        end
+      end
+
+      def copy_stimulus_controller_and_registry
+        say "Copying Stimulus controller and component registry...", :green
+        template "odt_registry.js", "app/javascript/odt_registry.js"
+        template "odt_component_controller.js", "app/javascript/controllers/odt_component_controller.js"
+        
+        # If stimulus manifest exists (rails stimulus:manifest:update)
+        if File.exist?("bin/rails")
+          run "bin/rails stimulus:manifest:update", abort_on_failure: false
+        end
+      end
+
+      def inject_stylesheets
+        say "Configuring ODT stylesheets...", :green
+
+        css_candidates = [
+          "app/assets/stylesheets/application.tailwind.css",
+          "app/assets/stylesheets/application.css",
+          "app/assets/stylesheets/application.scss",
+          "app/javascript/application.css",
+          "app/javascript/entrypoints/application.css"
+        ]
+
+        target_css = css_candidates.find { |file| File.exist?(file) }
+
+        if target_css
+          imports = %(\n/* ODT-Lightweight-UI tokens & styles */\n@import "odt-lightweight-ui/tokens.css";\n@import "odt-lightweight-ui/styles.css";\n)
+          append_to_file target_css, imports
+          say "Added ODT CSS imports to #{target_css}", :green
+        else
+          say "Could not automatically locate your main CSS file. Please add:\n  @import \"odt-lightweight-ui/tokens.css\";\n  @import \"odt-lightweight-ui/styles.css\";\nmanually to your application stylesheet.", :yellow
+        end
+      end
+
+      def show_finish_message
+        say ""
+        say "=========================================================", :cyan
+        say " 🎉 ODT-Lightweight-UI for Rails successfully installed!", :cyan
+        say "=========================================================", :cyan
+        say ""
+        say "Usage Example in any ERB view (.html.erb):"
+        say '  <%= odt_button "Click me", variant: "primary" %>'
+        say '  <%= odt_card title: "Profile" do %>'
+        say '    <%= odt_input :email, label: "Email" %>'
+        say '  <% end %>'
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/odt/templates/odt_component_controller.js

@@ -0,0 +1,48 @@
+import { Controller } from "@hotwired/stimulus";
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { ODT_COMPONENTS } from "../odt_registry";
+
+/**
+ * Stimulus Controller to mount and manage React component lifecycles in Rails.
+ * Compatible with Hotwire / Turbo navigation.
+ */
+export default class extends Controller {
+  static values = {
+    name: String,
+    props: Object,
+  };
+
+  connect() {
+    const Component = ODT_COMPONENTS[this.nameValue];
+
+    if (!Component) {
+      console.warn(`[ODT-UI-Rails] Component "${this.nameValue}" not found in ODT_COMPONENTS registry.`);
+      return;
+    }
+
+    this.root = ReactDOM.createRoot(this.element);
+    this.renderComponent(Component);
+  }
+
+  disconnect() {
+    if (this.root) {
+      this.root.unmount();
+      this.root = null;
+    }
+  }
+
+  propsValueChanged() {
+    if (this.root) {
+      const Component = ODT_COMPONENTS[this.nameValue];
+      if (Component) {
+        this.renderComponent(Component);
+      }
+    }
+  }
+
+  renderComponent(Component) {
+    const props = { ...(this.propsValue || {}) };
+    this.root.render(React.createElement(Component, props));
+  }
+}

data/lib/generators/odt/templates/odt_registry.js

@@ -0,0 +1,28 @@
+import * as ODT from 'odt-lightweight-ui';
+
+/**
+ * Registry mapping component names to ODT React components.
+ * Add custom components or wrappers here if needed.
+ */
+export const ODT_COMPONENTS = {
+  Button: ODT.Button,
+  Heading: ODT.Heading,
+  Text: ODT.Text,
+  Badge: ODT.Badge,
+  Avatar: ODT.Avatar,
+  Card: ODT.Card,
+  StatCard: ODT.StatCard,
+  ProgressBar: ODT.ProgressBar,
+  Input: ODT.Input,
+  TextArea: ODT.TextArea,
+  PasswordInput: ODT.PasswordInput,
+  SearchInput: ODT.SearchInput,
+  PinInput: ODT.PinInput,
+  Switch: ODT.Switch,
+  Checkbox: ODT.Checkbox,
+  Radio: ODT.Radio,
+  RadioGroup: ODT.RadioGroup,
+  Modal: ODT.Modal,
+  DropdownMenu: ODT.DropdownMenu,
+  Toaster: ODT.Toaster,
+};

data/lib/odt-ui-rails.rb

@@ -0,0 +1,6 @@
+require "odt_ui/version"
+require "odt_ui/helper"
+require "odt_ui/engine" if defined?(Rails)
+
+module OdtUi
+end

data/lib/odt_ui/engine.rb

@@ -0,0 +1,11 @@
+module OdtUi
+  class Engine < ::Rails::Engine
+    isolate_namespace OdtUi
+
+    initializer "odt_ui.helper" do
+      ActiveSupport.on_load(:action_view) do
+        include OdtUi::Helper
+      end
+    end
+  end
+end

data/lib/odt_ui/helper.rb

@@ -0,0 +1,102 @@
+require "json"
+
+module OdtUi
+  module Helper
+    # Generic component mount helper
+    # Example:
+    #   <%= odt_component :Button, variant: "primary" do %>
+    #     Submit
+    #   <% end %>
+    def odt_component(name, props = {}, html_options = {}, &block)
+      props_hash = props.dup
+
+      if block_given?
+        content = capture(&block)
+        props_hash[:children] = content.strip if content.present?
+      end
+
+      # Camelize keys if needed, or pass directly as camelCase
+      formatted_props = props_hash.transform_keys { |key| key.to_s.camelize(:lower) }
+
+      tag.div(
+        "",
+        class: ["odt-rails-root", html_options[:class]].compact.join(" "),
+        data: {
+          controller: "odt-component",
+          odt_component_name_value: name.to_s,
+          odt_component_props_value: formatted_props.to_json
+        },
+        **html_options.except(:class)
+      )
+    end
+
+    # =========================================================================
+    # Shorthand Component Helpers
+    # =========================================================================
+
+    def odt_button(label = nil, **props, &block)
+      props[:children] = label if label.present?
+      odt_component(:Button, props, &block)
+    end
+
+    def odt_heading(text = nil, level: 1, **props, &block)
+      props[:level] = level
+      props[:children] = text if text.present?
+      odt_component(:Heading, props, &block)
+    end
+
+    def odt_text(text = nil, **props, &block)
+      props[:children] = text if text.present?
+      odt_component(:Text, props, &block)
+    end
+
+    def odt_badge(label = nil, **props, &block)
+      props[:children] = label if label.present?
+      odt_component(:Badge, props, &block)
+    end
+
+    def odt_avatar(src: nil, name: nil, **props)
+      props[:src] = src if src.present?
+      props[:name] = name if name.present?
+      odt_component(:Avatar, props)
+    end
+
+    def odt_input(name = nil, **props)
+      props[:name] = name if name.present?
+      odt_component(:Input, props)
+    end
+
+    def odt_password_input(name = nil, **props)
+      props[:name] = name if name.present?
+      odt_component(:PasswordInput, props)
+    end
+
+    def odt_search_input(name = nil, **props)
+      props[:name] = name if name.present?
+      odt_component(:SearchInput, props)
+    end
+
+    def odt_card(**props, &block)
+      odt_component(:Card, props, &block)
+    end
+
+    def odt_stat_card(**props)
+      odt_component(:StatCard, props)
+    end
+
+    def odt_switch(name = nil, **props)
+      props[:name] = name if name.present?
+      odt_component(:Switch, props)
+    end
+
+    def odt_checkbox(name = nil, **props)
+      props[:name] = name if name.present?
+      odt_component(:Checkbox, props)
+    end
+
+    def odt_radio_group(name = nil, **props)
+      props[:name] = name if name.present?
+      odt_component(:RadioGroup, props)
+    end
+  end
+end

data/lib/odt_ui/version.rb

@@ -0,0 +1,3 @@
+module OdtUi
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: odt-ui-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ODT Team
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: Seamlessly mount and render ODT-Lightweight-UI components in Rails MVC
+  views via Hotwire Stimulus.
+email:
+- dev@odt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/generators/odt/install_generator.rb
+- lib/generators/odt/templates/odt_component_controller.js
+- lib/generators/odt/templates/odt_registry.js
+- lib/odt-ui-rails.rb
+- lib/odt_ui/engine.rb
+- lib/odt_ui/helper.rb
+- lib/odt_ui/version.rb
+homepage: https://github.com/PixxelTK/ODT-Lightweight-UI
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby on Rails integration and helpers for ODT-Lightweight-UI
+test_files: []