diff --git a/README.md b/README.md index 444040c..b6cb2cf 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,25 @@ This gem adds a simple way to automatically register custom elements in your `importmap-rails` app. No build step required! +## Table of Contents + +
+Click to expand + +- [Rails support](#rails-support) +- [Installation](#installation) +- [Generators](#generators) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) + +
+ +## Rails support + +* Supports Rails 7.0, 7.1, 7.2 & 8.0 +* Supports `importmap-rails` 1 and 2 + ## Installation Add this line to your application's Gemfile: @@ -14,19 +33,19 @@ gem "custom_elements-rails" Install the gem: -```bash +```console $ bundle install ``` Run the initial setup: -```bash +```console $ rails custom_elements:install ``` This will setup and edit add the following files: -``` +```graphql app/javascript ├── application.js └── custom_elements @@ -34,20 +53,16 @@ app/javascript └── index.js ``` -The `` custom element can be used in the views now. +The `` custom element can be used in views now. -You can generate a new custom element with `rails g custom_element abc`. +You can generate a new custom element `` with `rails generate custom_element demo`. -## How it works +### How It Works -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. +The `custom_elements-rails` gem uses `eagerDefineCustomElementsFrom` to automatically register [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) in the `custom_elements` folder. It parses the importmap generated by `importmap-rails` and registers custom elements using the `customElements.define(...)` API. -``` -custom_elements/hello_element.js // will register automatically -``` - -Your `*_element.js` files have to `export default` custom elements for this to work properly. +> [!IMPORTANT] +> Make sure your `*_element.js` files use `export default` to define the custom elements. ### Naming Convention for Custom Elements @@ -55,33 +70,30 @@ When defining custom elements from files, their filenames are used to generate t #### Usage -Register all files in the `custom_elements` folder as custom elements using a prefix (e.g., `app`): +Register all files in the `custom_elements` folder as custom elements: ```js eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); ``` +| Filepath | Generated Custom Element Name | +|--------------------------------------------:|:------------------------------| +| `custom_elements/demo_element.js` | `` | +| `custom_elements/demo-element.js` | `` | +| `custom_elements/foo_bar_element.js` | `` | +| `custom_elements/folder/foo_bar_element.js` | `` | + #### Conversion Rules - Filenames are transformed into kebab-case (lowercase with hyphens). -- Words are separated by underscores (`_`) or hyphens (`-`) in the filename. - The folder structure is reflected in the name using double hyphens (`--`) to separate folder names from the file name. -- A prefix (e.g., `app`) is added to the beginning of each custom element name. - -#### Examples - -| Filepath | Generated Custom Element Name | -|-------------------------------------|--------------------------------| -| `custom_elements/demo_element.js` | `` | -| `custom_elements/demo-element.js` | `` | -| `custom_elements/foo_bar_element.js`| `` | -| `custom_elements/folder/foo_bar_element.js` | `` | +- A [configurable prefix](#documentation) is added to the beginning of each custom element name. -## Add a custom element with the built-in generator +## Generators This gem adds a generator to generate new custom elements with: -```bash +```console $ rails generate custom_element test ``` @@ -102,13 +114,13 @@ export default class extends HTMLElement { which in turn will register a `` custom element automatically in your app. -```bash +```console $ 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 +```console $ rails generate custom_element test attribute1 ``` @@ -136,13 +148,15 @@ export default class extends HTMLElement { `eagerDefineCustomElementsFrom(under, options)` -Currently supported `options`: +Currently supported optional `options`: -* `prefix`: The custom elements namespace/prefix. +* `prefix`: The custom elements namespace. (default: "app") ## Contributing -TODO +1. Fork the repository. +2. Create a feature branch. +3. Submit a pull request with a detailed description of changes. ## License diff --git a/app/assets/javascript/custom_elements-rails.js b/app/assets/javascript/custom_elements-rails.js index 73dc1c7..dc35e88 100644 --- a/app/assets/javascript/custom_elements-rails.js +++ b/app/assets/javascript/custom_elements-rails.js @@ -1,4 +1,9 @@ export function eagerDefineCustomElementsFrom(namespace, options = {}) { + const defaultOptions = { + prefix: 'app' + } + + options = { ...defaultOptions, ...options } const pathToElementName = (path) => { const parts = path.split('/').map(p => p.replace(/_/g, '-')); return `${options.prefix}-${parts.slice(0, -1).join('--')}${parts.length > 1 ? '--' : ''}${parts.at(-1)}`; diff --git a/test/dummy/app/javascript/custom_elements/index.js b/test/dummy/app/javascript/custom_elements/index.js index d0f0e54..3839b82 100644 --- a/test/dummy/app/javascript/custom_elements/index.js +++ b/test/dummy/app/javascript/custom_elements/index.js @@ -1,3 +1,3 @@ import { eagerDefineCustomElementsFrom } from "custom_elements-rails" -eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }) +eagerDefineCustomElementsFrom("custom_elements")