custom_elements-rails 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b77ebf93580a7eb3cb83365dc83ba086f6d3bb1f20e173020039c08c5234669c
-  data.tar.gz: fc62a709561eeeefdae11cac69983062664d21065e058b376932258d3d1a522a
+  metadata.gz: 00a594ba7a841b984e65721f217af0248ba150fe032038db7d6501606900fc14
+  data.tar.gz: 9db69aa3b4a6f8e621631dc22dad1640af90aafc2b6ec2fbc090089cb28d69e4
 SHA512:
-  metadata.gz: bb09a978e032b95385a14b5a2e7ef060edd995981466eb941cef16c423bf27ba00ab012f9169e9502ea40c60308014b19fcdc8e3d1601b3f57c847d830cd276b
-  data.tar.gz: b7dc6b1f79854aa70ae148222eb8093d772cb647f927dc7d73f4d8a7b0202389c4f5f80db1f2645bb21c8982e4785aa1097365fd521521d12a9670b3100a8ebf
+  metadata.gz: 47d8050c6e7e08715d63169ed4040f3d422652ba69140d84d2d269941184d0270281115b77f5f1413e4de62b7ba1efffcc0f78da3004fa95095c1a83e4efd907
+  data.tar.gz: 6b52ed941852c7543bbf0f9f82d5f6631bf06ea956248ac828d8660511894a7e189a9f0a459439053f7fd461d228c097db6d5ad16481c50fca7ea59013d0053f

data/README.md

@@ -1,10 +1,11 @@
-# Custom Elements with Rails
+# Custom Elements Rails
 
-This gem provides a small js-helper, installation and generators to use custom elements in conjunction with `importmap-rails`.
+[![Tests](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml)
 
-## Usage
+This gem adds a simple way to automatically register custom elements in your `importmap-rails` app. No build step required!
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -23,7 +24,7 @@ Run the initial setup:
 $ rails custom_elements:install
 ```
 
-This will setup and add the following files:
+This will setup and edit add the following files:
 
 ```
 app/javascript
@@ -33,25 +34,27 @@ app/javascript
     └── index.js
 ```
 
-You can now add the `<app-hello>` custom element in your HTML. No build step needed.
+The `<app-hello>` custom element can be used in the views now.
+
+You can generate a new custom element with `rails g custom_element abc`.
 
 ## How it works
 
-`eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" })` will parse the JSON-importmap rendered by the `importmap-rails` gem and register custom elements with `customElements.define(...)` to the browser's custom element registry.
+The setup will add a JS function call `eagerDefineCustomElementsFrom` that parses the importmap rendered by the `importmap-rails` gem.
+It registers custom elements with `customElements.define(...)` in the browser's registry based on the filenames in the `custom_elements` folder automatically.
 
 ```
-custom_elements/hello_element.js // will register <app-hello>
+custom_elements/hello_element.js // will register <app-hello> automatically
 ```
 
-Your `_element.js` files have to `export default` custom elements for this to work.
+Your `*_element.js` files have to `export default` custom elements for this to work properly.
 
 > [!WARNING]  
-> Only single word elements are support currently.
-
+> Only single word elements are supported currently. See https://github.com/codergeek121/custom_elements-rails/issues/1
 
-## Add a custom element
+## Add a custom element with the built-in generator
 
-Generate a new custom element with:
+This gem adds a generator to generate new custom elements with:
 
 ```bash
 $ rails generate custom_element test 
@@ -59,13 +62,58 @@ $ rails generate custom_element test
 
 This will generate 
 
+```javascript
+// app/javascript/custom_elements/test_element.js
+export default class extends HTMLElement {
+  constructor() {
+    super()
+  }
+
+  connectedCallback() {
+    console.log("test_element.js")
+  }
+}
 ```
-app/javascript
-└── custom_elements
-    └── test_element.js
+
+which in turn will register a `<app-test></app-test>` custom element automatically in your app.
+
+```bash
+$ rails generate custom_element test 
+```
+
+To observe changes in your custom element's attributes, you need to set a static array of attribute names. The generator also supports setting those automatically:
+
+```bash
+$ rails generate custom_element test attribute1
 ```
 
-which in turn will register a `<app-test></app-test>` custom element.
+will generate
+
+```javascript
+export default class extends HTMLElement {
+  static observedAttributes = ["attribute1"]
+
+  constructor() {
+    super()
+  }
+
+  connectedCallback() {
+    console.log("test_element.js")
+  }
+
+  get attribute1() {
+    return this.getAttribute("attribute1")
+  }
+}
+```
+
+## Documentation
+
+`eagerDefineCustomElementsFrom(under, options)`
+
+Currently supported `options`:
+
+* `prefix`: The custom elements namespace/prefix.
 
 ## Contributing
 

data/Rakefile

@@ -1,3 +1,6 @@
-require "bundler/setup"
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
 
 require "bundler/gem_tasks"

data/lib/custom_elements/rails/railtie.rb

@@ -2,7 +2,9 @@ module CustomElements
   module Rails
     class Railtie < ::Rails::Engine
       initializer "custom_elements-rails.assets.precompile" do |app|
-        app.config.assets.precompile += %w( custom_elements-rails.js )
+        if app.config.respond_to? :assets
+          app.config.assets.precompile += %w( custom_elements-rails.js )
+        end
       end
     end
   end

data/lib/custom_elements/rails/version.rb

@@ -1,5 +1,5 @@
 module CustomElements
   module Rails
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

data/lib/generators/custom_element_generator.rb

@@ -1,6 +1,8 @@
 class CustomElementGenerator < Rails::Generators::NamedBase
   source_root File.expand_path("templates", __dir__)
 
+  argument :attributes, type: :array, default: [], banner: "Observed attributes"
+
   def copy_custom_element
     template "custom_element.js", "app/javascript/custom_elements/#{file_name}_element.js"
   end

data/lib/generators/templates/custom_element.js.tt

@@ -1,4 +1,7 @@
 export default class extends HTMLElement {
+<% if attributes.any? %>
+  static observedAttributes = <%= attributes.map { _1.name } %>
+<% end %>
   constructor() {
     super()
   }
@@ -6,4 +9,10 @@ export default class extends HTMLElement {
   connectedCallback() {
     console.log("<%= file_name %>")
   }
+<% attributes.each do |attribute| -%>
+
+  get <%= attribute.name %>() {
+    return this.getAttribute("<%= attribute.name %>")
+  }
+<% end -%>
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: custom_elements-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Niklas Häusele
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-22 00:00:00.000000000 Z
+date: 2024-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: 7.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 'A simple way to use custom elements to your Rails app. #nobuild'
 email:
 - niklas.haeusele@hey.com