lite-component 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 775fd8e9a6f315ab425672710cc83fa654b081909a670b4b849ec7b4753401b3
+  data.tar.gz: 12b66c28eed78a0551d55596a2d0361d08da68c83e0c85cde7cdd9b50e57e963
+SHA512:
+  metadata.gz: cb132f66e10923ab98013677ccb5c0ec6a502c05895d45d7d91b8584da259e1f9211c87d965c7c960aa79884f7103d974b65a21386c28b68dfeb731bc46bf421
+  data.tar.gz: cf33d78401b9eb07adba8ea39161a5d6166b0fcfb264c06d92e3c1acb89004ff23ad22304737156d12df8beefc1c36f0f2f4383b03447cbf8d50cde255375d8e

data/.fasterer.yml

@@ -0,0 +1,19 @@
+speedups:
+  block_vs_symbol_to_proc: true
+  each_with_index_vs_while: false
+  fetch_with_argument_vs_block: true
+  for_loop_vs_each: true
+  getter_vs_attr_reader: true
+  gsub_vs_tr: true
+  hash_merge_bang_vs_hash_brackets: true
+  keys_each_vs_each_key: true
+  map_flatten_vs_flat_map: true
+  module_eval: true
+  proc_call_vs_yield: true
+  rescue_vs_respond_to: true
+  reverse_each_vs_reverse_each: true
+  select_first_vs_detect: true
+  select_last_vs_reverse_detect: true
+  setter_vs_attr_writer: true
+  shuffle_first_vs_sample: true
+  sort_vs_sort_by: true

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,4 @@
+--backtrace
+--color
+--format progress
+--order random

data/.rubocop.yml

@@ -0,0 +1,30 @@
+require:
+  - rubocop-performance
+  - rubocop-rspec
+AllCops:
+  TargetRubyVersion: 2.6
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+Layout/EmptyLinesAroundBlockBody:
+  Exclude:
+    - 'spec/**/**/*'
+Layout/EmptyLinesAroundClassBody:
+  EnforcedStyle: empty_lines_except_namespace
+Layout/EmptyLinesAroundModuleBody:
+  EnforcedStyle: empty_lines_except_namespace
+Metrics/BlockLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/LineLength:
+  Max: 100
+Naming/FileName:
+  Enabled: false
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/ExpandPathArguments:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,24 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+- 2.5
+- 2.6
+- ruby-head
+matrix:
+  fast_finish: true
+  allow_failures:
+  - rvm: ruby-head
+before_install:
+- gem update --system
+- gem install bundler
+install:
+- bundle install --jobs=3 --retry=3
+script:
+- bundle exec rspec
+- bundle exec rubocop
+- bundle exec fasterer
+notifications:
+  email: false
+  slack:
+    secure: mtfWWZthR1xe+vfHViVYno4doSLn9ENWoDumbhnoUcanYLlhqfnGY4U9Jde6QvoxKlcrAudOwyuD9DvwmtgEduhJbAi3fydHpeDGdL5opDqhQ7uaT8Gx93I9cYh/A4kf+GscUcFUqiRjH1IdT64ysfTVfBNXR9mxBNxGJa/qcE5Vq/N6loEtDabKoStknxBJPsKTzSWrx5zSa3a3q+fdLT4XTfxYisRiTssMEqfAY9vcHqYAwZ1KJk/mQ4GrWUNJPOvHrMW6u9/wKT2nv2Tfg6mM5G7q7WCF6AiZ6ZTlgVMyXylH+YhyEJpOSwhIkILDU+/1RR2JUKMb0aafps3+GHF7gPpubtPwMISj6Nb9mmoin68KD7xS/fs5X0BZZ7Hj6PBgrZJZLYunoQqKmE4MGp6UK2BwAS/cV1iv2QTxkN9NkJW2SSZCsEzK1SaZFIK8Z0R3Kvk6ntZhpNY4tR/RKXPbHYrGugZSNWhwyRYSwXSNOdkIbVgV2ukKPLvFi9t3mQuGIRbpgtvBB8sBx8xg72sH6wIuH7bh/lTjwWP08NPH666P/9a3BFwJSynS2JFE0g1kIrJDt8J85adhmxAm9Akybqmdti9C1UmLwOOT9Jtz1f+yy4Qf0+5umFiQ6ggVDbAS9OwK9t2tJKSzMmlSWgfufqKHDPHa9ATEgAe1l+M=

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2019-12-10
+### Added
+- Initial project version

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at j.gomez@drexed.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in lite-component.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,192 @@
+PATH
+  remote: .
+  specs:
+    lite-component (1.0.0)
+      rails (>= 5.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.0.1)
+      actionpack (= 6.0.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.0.1)
+      actionpack (= 6.0.1)
+      activejob (= 6.0.1)
+      activerecord (= 6.0.1)
+      activestorage (= 6.0.1)
+      activesupport (= 6.0.1)
+      mail (>= 2.7.1)
+    actionmailer (6.0.1)
+      actionpack (= 6.0.1)
+      actionview (= 6.0.1)
+      activejob (= 6.0.1)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.0.1)
+      actionview (= 6.0.1)
+      activesupport (= 6.0.1)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.0.1)
+      actionpack (= 6.0.1)
+      activerecord (= 6.0.1)
+      activestorage (= 6.0.1)
+      activesupport (= 6.0.1)
+      nokogiri (>= 1.8.5)
+    actionview (6.0.1)
+      activesupport (= 6.0.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.0.1)
+      activesupport (= 6.0.1)
+      globalid (>= 0.3.6)
+    activemodel (6.0.1)
+      activesupport (= 6.0.1)
+    activerecord (6.0.1)
+      activemodel (= 6.0.1)
+      activesupport (= 6.0.1)
+    activestorage (6.0.1)
+      actionpack (= 6.0.1)
+      activejob (= 6.0.1)
+      activerecord (= 6.0.1)
+      marcel (~> 0.3.1)
+    activesupport (6.0.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2)
+    ast (2.4.0)
+    builder (3.2.4)
+    colorize (0.8.1)
+    concurrent-ruby (1.1.5)
+    crass (1.0.5)
+    diff-lcs (1.3)
+    erubi (1.9.0)
+    fasterer (0.8.1)
+      colorize (~> 0.7)
+      ruby_parser (>= 3.14.1)
+    generator_spec (0.9.4)
+      activesupport (>= 3.0.0)
+      railties (>= 3.0.0)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    i18n (1.7.0)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    loofah (2.4.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    method_source (0.9.2)
+    mimemagic (0.3.3)
+    mini_mime (1.0.2)
+    mini_portile2 (2.4.0)
+    minitest (5.13.0)
+    nio4r (2.5.2)
+    nokogiri (1.10.7)
+      mini_portile2 (~> 2.4.0)
+    parallel (1.19.1)
+    parser (2.6.5.0)
+      ast (~> 2.4.0)
+    rack (2.0.7)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.0.1)
+      actioncable (= 6.0.1)
+      actionmailbox (= 6.0.1)
+      actionmailer (= 6.0.1)
+      actionpack (= 6.0.1)
+      actiontext (= 6.0.1)
+      actionview (= 6.0.1)
+      activejob (= 6.0.1)
+      activemodel (= 6.0.1)
+      activerecord (= 6.0.1)
+      activestorage (= 6.0.1)
+      activesupport (= 6.0.1)
+      bundler (>= 1.3.0)
+      railties (= 6.0.1)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.0.1)
+      actionpack (= 6.0.1)
+      activesupport (= 6.0.1)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.20.3, < 2.0)
+    rainbow (3.0.0)
+    rake (13.0.1)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.0)
+      rspec-support (~> 3.9.0)
+    rspec-expectations (3.9.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.0)
+    rubocop (0.77.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    rubocop-performance (1.5.1)
+      rubocop (>= 0.71.0)
+    rubocop-rspec (1.37.0)
+      rubocop (>= 0.68.1)
+    ruby-progressbar (1.10.1)
+    ruby_parser (3.14.1)
+      sexp_processor (~> 4.9)
+    sexp_processor (4.13.0)
+    sprockets (4.0.0)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (0.20.3)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.6.0)
+    websocket-driver (0.7.1)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.4)
+    zeitwerk (2.2.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  fasterer
+  generator_spec
+  lite-component!
+  rake
+  rspec
+  rubocop
+  rubocop-performance
+  rubocop-rspec
+
+BUNDLED WITH
+   2.0.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Juan Gomez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,470 @@
+# Lite::Component
+
+[![Gem Version](https://badge.fury.io/rb/lite-component.svg)](http://badge.fury.io/rb/lite-component)
+[![Build Status](https://travis-ci.org/drexed/lite-component.svg?branch=master)](https://travis-ci.org/drexed/lite-component)
+
+Lite::Component is a library for building component base objects. This technique simplifies
+and organizes often used or logically comply page objects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lite-component'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install lite-component
+
+## Table of Contents
+
+* [Setup](#setup)
+  * [Generator](#generator)
+  * [Assets](#assets)
+  * [Components](#components)
+* [Usage](#usage)
+  * [Attribute and blocks](#attributes-and-blocks)
+  * [Attributes defaults](#attribute-defaults)
+  * [Attributes overrides](#attribute-overrides)
+  * [Elements](#elements)
+  * [Helper methods](#helper-methods)
+  * [Rendering components without a partial](#rendering-components-without-a-partial)
+  * [Namespaced components](#namespaced-components)
+
+## Setup
+
+### Generator
+
+Use `rails g component NAME` will generate the following files:
+```
+/app/assets/javascripts/components/[name].js
+/app/assets/stylesheets/components/[name].scss
+/app/components/[name]_query.rb
+/app/views/components/_[name].html.erb
+```
+The generator also takes `--skip-css`, `--skip-js` and `--skip-erb` options
+
+### Assets
+
+In the basic Rails app setup component `*.scss` and `*.js` will be automatically load
+via the tree lookup.
+
+In order to require assets such manually require them in the manifest, e.g. `application.css`:
+
+```
+/*
+ * All components:
+ *= require lite-component
+ *
+ * - or -
+ *
+ * Specific component:
+ *= require component/alert
+ */
+```
+
+### Components
+
+If you create a `ApplicationComponent` file in the `app/components` directory, the generator
+will create file that inherit from `ApplicationComponent` if not `Lite::Component::Base`.
+
+## Usage
+
+### Attributes and blocks
+
+There are two ways of passing data to components: `attributes` and `blocks`. Attributes are useful for data such as ids, modifiers and data structures (models, etc). Blocks are useful when you need
+to inject HTML content into components.
+
+```ruby
+# app/components/alert_component.rb
+
+class AlertComponent < Components::Component
+  attribute :context
+  attribute :message
+end
+```
+
+```erb
+<% # app/views/components/_alert.html.erb %>
+
+<div class="alert alert--<%= alert.context %>" role="alert">
+  <%= alert.message %>
+</div>
+```
+
+```erb
+<%= component "alert", message: "Something went right!", context: "success" %>
+<%= component AlertComponent, message: "Something went wrong!", context: "danger" %>
+```
+
+To inject some text or HTML content into our component we can print the component variable in our template, and populate it by passing a block to the component helper:
+
+```erb
+<% # app/views/components/_alert.html.erb %>
+
+<div class="alert alert--<%= alert.context %>" role="alert">
+  <%= alert %>
+</div>
+```
+
+```erb
+<%= component "alert", context: "success" do %>
+  <em>Something</em> went right!
+<% end %>
+```
+
+Another good use case for attributes is when you have a component backed by a model:
+
+```ruby
+# app/components/comment_component.rb
+
+class CommentComponent < Components::Component
+  attribute :comment
+
+  delegate :id, :author, :body, to: :comment
+end
+```
+
+```erb
+<% # app/views/components/_comment.html.erb %>
+
+<div id="comment-<%= comment.id %>" class="comment">
+  <div class="comment__author">
+    <%= link_to comment.author.name, author_path(comment.author) %>
+  </div>
+  <div class="comment__body">
+    <%= comment.body %>
+  </div>
+</div>
+```
+
+```erb
+<% comments.each do |comment| %>
+  <%= component "comment", comment: comment %>
+<% end %>
+```
+
+### Attribute defaults
+
+Attributes can have default values:
+
+```ruby
+# app/components/alert_component.rb
+
+class AlertComponent < Components::Component
+  attribute :message
+  attribute :context, default: "primary"
+end
+```
+
+### Attribute overrides
+
+It's easy to override an attribute with additional logic:
+
+```ruby
+# app/components/alert_component.rb
+
+class AlertComponent < Components::Component
+  attribute :message
+  attribute :context, default: "primary"
+
+  def message
+    @message.upcase if context == "danger"
+  end
+end
+```
+
+### Attribute validation
+
+To ensure your components get initialized properly you can use `ActiveModel::Validations` in your elements or components:
+
+```ruby
+# app/components/alert_component.rb
+
+class AlertComponent < Components::Component
+  attribute :label
+
+  validates :label, presence: true
+end
+```
+
+Your validations will be executed during the components initialization and raise an `Lite::Component::ValidationError` if any validation fails.
+
+### Elements
+
+Attributes and blocks are great for simple components or components backed by a data structure, such as a model. Other components are more generic in nature and can be used in a variety of contexts. Often they consist of multiple parts or elements, that sometimes repeat, and sometimes need their own modifiers.
+
+Take a card component. In React, a common approach is to create subcomponents:
+
+```jsx
+<Card flush={true}>
+  <CardHeader centered={true}>
+    Header
+  </CardHeader>
+  <CardSection size="large">
+    Section 1
+  </CardSection>
+  <CardSection size="small">
+    Section 2
+  </CardSection>
+  <CardFooter>
+    Footer
+  </CardFooter>
+</Card>
+```
+
+There are two problems with this approach:
+
+1. The card header, section and footer have no standalone meaning, yet we treat them as standalone components. This means a `CardHeader` could be placed outside of a `Card`.
+2. We lose control of the structure of the elements. A `CardHeader` can be placed below, or inside a `CardFooter`.
+
+Using this gem, the same component can be written like this:
+
+```ruby
+# app/components/card_component.rb
+
+class CardComponent < Components::Component
+  attribute :flush, default: false
+
+  element :header do
+    attribute :centered, default: false
+  end
+
+  element :section, multiple: true do
+    attribute :size
+  end
+
+  element :footer
+end
+```
+
+```erb
+<% # app/views/components/_card.html.erb %>
+
+<div class="card <%= "card--flush" if card.flush %>">
+  <div class="card__header <%= "card__header--centered" if card.header.centered %>">
+    <%= card.header %>
+  </div>
+  <% card.sections.each do |section| %>
+    <div class="card__section <%= "card__section--#{section.size}" %>">
+      <%= section %>
+    </div>
+  <% end %>
+  <div class="card__footer">
+    <%= card.footer %>
+  </div>
+</div>
+```
+
+Elements can be thought of as isolated subcomponents, and they are defined on the component. Passing `multiple: true` makes it a repeating element, and passing a block lets us declare attributes on our elements, in the same way we declare attributes on components.
+
+In order to populate them with data, we pass a block to the component helper, which yields the component, which lets us set attributes and blocks on the element in the same way we do for components:
+
+```erb
+<%= component "card", flush: true do |c| %>
+  <% c.header centered: true do %>
+    Header
+  <% end %>
+  <% c.section size: "large" do %>
+    Section 1
+  <% end %>
+  <% c.section size: "large" do %>
+    Section 2
+  <% end %>
+  <% c.footer do %>
+    Footer
+  <% end %>
+<% end %>
+```
+
+Multiple calls to a repeating element, such as `section` in the example above, will append each section to an array.
+
+Another good use case is a navigation component:
+
+```ruby
+# app/components/navigation_component.rb
+
+class NavigationComponent < Components::Component
+  element :items, multiple: true do
+    attribute :label
+    attribute :url
+    attribute :active, default: false
+  end
+end
+```
+
+```erb
+<%= component "navigation" do |c| %>
+  <% c.item label: "Home", url: root_path, active: true %>
+  <% c.item label: "Explore" url: explore_path %>
+<% end %>
+```
+
+An alternative here is to pass a data structure to the component as an attribute, if no HTML needs to be injected when rendering the component:
+
+```erb
+<%= component "navigation", items: items %>
+```
+
+Elements can have validations, too:
+
+```ruby
+# app/components/navigation_component.rb
+
+class NavigationComponent < Components::Component
+  element :items, multiple: true do
+    attribute :label
+    attribute :url
+    attribute :active, default: false
+
+    validates :label, presence: true
+    validates :url, presence: true
+  end
+end
+```
+
+Elements can also be nested, although it is recommended to keep nesting to a minimum:
+
+```ruby
+# app/components/card_component.rb
+
+class CardComponent < Components::Component
+  ...
+
+  element :section, multiple: true do
+    attribute :size
+
+    element :header
+    element :footer
+  end
+end
+```
+
+### Helper methods
+
+In addition to declaring attributes and elements, it is also possible to declare helper methods. This is useful if you prefer to keep logic out of your templates. Let's extract the modifier logic from the card component template:
+
+```ruby
+# app/components/card_component.rb
+
+class CardComponent < Components::Component
+  ...
+
+  def css_classes
+    css_classes = ["card"]
+    css_classes << "card--flush" if flush
+    css_classes.join(" ")
+  end
+end
+```
+
+```erb
+<% # app/views/components/_card.html.erb %>
+
+<%= content_tag :div, class: card.css_classes do %>
+  ...
+<% end %>
+```
+
+It's even possible to declare helpers on elements:
+
+```ruby
+# app/components/card_component.rb %>
+
+class CardComponent < Components::Component
+  ...
+
+  element :section, multiple: true do
+    attribute :size
+
+    def css_classes
+      css_classes = ["card__section"]
+      css_classes << "card__section--#{size}" if size
+      css_classes.join(" ")
+    end
+  end
+end
+```
+
+```erb
+<% # app/views/components/_card.html.erb %>
+
+<%= content_tag :div, class: card.css_classes do %>
+  ...
+  <%= content_tag :div, class: section.css_classes do %>
+    <%= section %>
+  <% end %>
+  ...
+<% end %>
+```
+
+Helper methods can also make use of the `@view` instance variable in order to call Rails helpers such as `link_to` or `content_tag`.
+
+### Rendering components without a partial
+
+For some small components, such as buttons, it might make sense to skip the partial altogether, in order to speed up rendering. This can be done by overriding `render` on the component:
+
+```ruby
+# app/components/button_component.rb
+
+class ButtonComponent < Components::Component
+  attribute :label
+  attribute :url
+  attribute :context
+
+  def render
+    @view.link_to label, url, class: css_classes
+  end
+
+  def css_classes
+    css_classes = "button"
+    css_classes << "button--#{context}" if context
+    css_classes.join(" ")
+  end
+end
+```
+
+```erb
+<%= component "button", label: "Sign up", url: sign_up_path, context: "primary" %>
+<%= component ButtonComponent, label: "Sign in", url: sign_in_path %>
+```
+
+### Namespaced components
+
+Components can be nested under a namespace. This is useful if you want to practice things like [Atomic Design](http://bradfrost.com/blog/post/atomic-web-design/), [BEMIT](https://csswizardry.com/2015/08/bemit-taking-the-bem-naming-convention-a-step-further/) or any other component classification scheme. In order to create a namespaced component, stick it in a folder and wrap the class in a module:
+
+```ruby
+module Objects
+  class MediaObject < Components::Component; end
+end
+```
+
+Then call it from a template like so:
+
+```erb
+<%= component "objects/media_object" %>
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lite-component. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Lite::Component project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/lite-component/blob/master/CODE_OF_CONDUCT.md).