barnardos-ruby_design_system 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f3547e71601e1103ceda6447e1f8eb34d5ac33d6aec20330daf23c825ea3f1f
-  data.tar.gz: f000043b2a23cc728f31e1de399fe2cd8d31086f1fdc2fe40732c65279eea790
+  metadata.gz: e03581346f2bd984e9f80cf1dcac60707ec00c32264bae1595ed0eab9bea9b8a
+  data.tar.gz: dacbc3dfd60c95e9d89b7057e368a5ad1f533b7719ea3a1260e9a603c4d49aa4
 SHA512:
-  metadata.gz: 8f0d56811483953ddc7933d2e699c5716ef7f674307d6a4f4c59532420282cee62a75574dab7a48d719a0ffdf10929b57270df624ab29e8cc9c3e79899c9faf5
-  data.tar.gz: 585df7f643bca237738da845befa08c280b8b796d826564658d407002e0208881f983acf47edf96a0cb7370269de3b6f8e6efd3db1d1a7cec259c6a75049fde9
+  metadata.gz: 7dfd3577281af4df7a2f04e46d661293610ff3adcbde20d34fd2fc703549cd943f6226aeba3a9b8d99c18790530198828c1f1c9bf7e02bc1646d24dd858c88ba
+  data.tar.gz: 44405b41e33d7471323516b2885317187204e02ffac3d50474f5516f630a53add3d560b4123742ec37fd095f73199cf665723208ab07fc639b897a4d861272d8

data/README.md

@@ -1,6 +1,6 @@
 # Barnardos::RubyDesignSystem
 
-Tools for appling Barnardo's Design System to Ruby projects.
+Tools for applying Barnardo's Design System to Ruby projects.
 
 The tools include helper methods and modification to simple form to make it Design System compliant.
 
@@ -16,11 +16,30 @@ And then execute:
 
     $ bundle
 
-### Installing PostCSS
+With the gem install, a Rails generator is added that will set up the host app. To run the generator
+execute the following at app root:
+
+    $ rails g barnardos:install
+
+Then restart the server and the changes should take effect.
+
+Have a look at `lib/generators/barnardos/install_generator.rb` for the details of the generator's actions.
+
+As an outline it does the following:
+
+### Installs the barnardos components in the webpaker environment
+
+These provide the CSS and JS needed for the components to work properly
+
+### Installs PostCSS
 
 The CSS used in the Design System requires processing in JavaScript space by PostCSS.
 
-#### `/app/views/layouts/application.html.erb`
+The file `package.json` is updated to include declarations for PostCSS and related plugins.
+
+The PostCSS configuration file `/postcss.config.js` is copied to root
+
+#### Updates `/app/views/layouts/application.html.erb`
 
 All CSS should be defined within the folder `app/javascript` so the `stylesheet_link_tag` declaration can be removed
 from the application template. Also make sure that JavaScript is loaded here with `javascript_pack_tag`. For example:
@@ -29,69 +48,22 @@ from the application template. Also make sure that JavaScript is loaded here wit
   <%= javascript_pack_tag 'application' %>
 ```
 
-#### `/package.json`
-
-Update `package.json` to include declarations for PostCSS and related plugins.
-
-Also while this file is being modified, add `@barnardos/components` which will make the Design System code
-available.
+### Sets up simple form to work with the design system
 
-For example:
+A set of classes are inserted into `app/inputs`. These modify the rails input classes so that when used
+with simple_form, they create components that match the design system.
 
-```json
-{
-  "name": "my_app",
-  "private": true,
-  "dependencies": {
-    "@barnardos/components": "^1.0.0",
-    "@rails/actioncable": "^6.0.0-alpha",
-    "@rails/activestorage": "^6.0.0-alpha",
-    "@rails/ujs": "^6.0.0-alpha",
-    "@rails/webpacker": "^4.0.7",
-    "polyfill-nodelist-foreach": "^1.0.1",
-    "postcss-browser-reporter": "^0.6.0",
-    "postcss-import": "^12.0.1",
-    "postcss-inline-svg": "^4.1.0",
-    "postcss-preset-env": "^6.7.0",
-    "postcss-reporter": "^6.0.1",
-    "postcss-svgo": "^4.0.2"
-  },
-  "version": "0.1.0",
-  "devDependencies": {
-    "webpack-dev-server": "^3.9.0"
-  }
-}
-```
+## Using the components
 
-#### `/postcss.config.js`
+### `app/helpers/application_helper.rb`
 
-A PostCSS configuration file is also present. The following is an example that works with the Design System:
+To use the helper methods defined in this gem, add the following to `ApplicationHelper`:
 
-```javascript
-module.exports = () => ({
-  plugins: [
-    require("postcss-import"),
-    require("postcss-preset-env")({
-      autoprefixer: {},
-      features: {
-        "focus-within": true,
-        "nesting-rules": true,
-        "color-mod-function": {
-          unresolved: "warn"
-        },
-        "custom-properties": {
-          preserve: false,
-          warnings: true
-        }
-      }
-    }),
-    require("postcss-browser-reporter"),
-    require("postcss-reporter")
-  ]
-});
+```ruby
+include Barnardos::RubyDesignSystem::ComponentHelper
 ```
 
-#### `/app/javascript/packs/application.js`
+### `/app/javascript/packs/application.js`
 
 For each Design System component you wish to use in the app, add a line to `application.js` in the form:
 
@@ -113,21 +85,6 @@ import "@barnardos/components/src/components/Title/index.css";
 This will load the associated CSS where it can be processed by PostCSS. The list of imports can get quite long, so
 placing them in alphabetical order is a good idea as it makes them a little easier to manage.
 
-#### Complete PostCSS installation
-
-The following two commands will clear out the current Webpacker setup and install the requires elements:
-
-```bash
-rake webpacker:clobber
-yarn
-```
-
-Then restart the server and the changes should take effect.
-
-## Usage
-
-TODO: Write usage instructions here
-
 ## 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.

data/lib/barnardos/ruby_design_system/component_helper.rb

@@ -1,6 +1,19 @@
 module Barnardos
   module RubyDesignSystem
+    # Provides helper methods available in the host app's server.
+    #
+    # Usage: Add the following to `/app/helpers/application_helper.rb` within the module `ApplicationHelper`:
+    #
+    #   include Barnardos::RubyDesignSystem::ComponentHelper
+    #
     module ComponentHelper
+
+      # Creates a ProminentLink Component.
+      #
+      # @param name [String] Link text that appears on page
+      # @param options Same as `link_to` see {https://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to Rails API}
+      # @param html_options [Hash] Also same as `link_to` with additional option `colour` which sets the ProminentLink colour
+      # @return [String] HTML anchor with class `ProminentLink` and optionally `ProminentLink--<colour>` if colour entered
       def prominent_link(name = nil, options = nil, html_options = {}, &block)
         colour = html_options.delete(:colour)
         colour_class = colour && "ProminentLink--#{colour}"
@@ -8,20 +21,37 @@ module Barnardos
         link_to(name, options, html_options, &block)
       end
 
+      # Creates a SkipLink Component
+      #
+      # @param text [String] Link text that appears on page
+      # @param anchor [String] the anchor name that is the target for the skip link
+      # @return [String] HTML anchor with class `SkipLink`
       def skip_link(text, anchor: '#main-anchor')
         link_to text, anchor, class: 'SkipLink'
       end
 
+      # Creates a Link Component
+      #
+      # All parameters are as `link_to` see {https://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to Rails API}
+      # @return [String] HTML anchor with class `Link`
       def link(name = nil, options = nil, html_options = {}, &block)
         html_options[:class] = [html_options[:class], 'Link'].flatten.compact
         link_to(name, options, html_options, &block)
       end
 
+      # Overrides the Rails helper method `link_to`
+      # Adds the `html_options` option `new_window` which changes the link so that it will link to a new window
+      # @return [String] HTML anchor with `target` set as `_blank` if html_options include `new_window: true`
       def link_to(name = nil, options = nil, html_options = {}, &block)
         html_options[:target] = '_blank' if html_options.delete(:new_window)
         super
       end
 
+      # Creates a FieldSet Component around passed in block. Also adds Fieldset-children inner wrapper around block
+      #
+      # @param legend [String] outputs into a Fieldset-legend component within the Fieldset if set
+      # @param hint [String] outputs into a Hint component within the Fieldset if set
+      # @return [String] HTML containing the passed in block wrapped by a Fieldset Component and sub components
       def fieldset(legend: nil, hint: nil)
         content_tag :fieldset, class: 'Fieldset' do
           concat(content_tag(:legend, legend, class: 'Fieldset-legend')) if legend

data/lib/barnardos/ruby_design_system/inputs/collection_check_boxes_input.rb

@@ -3,6 +3,22 @@
 module Barnardos
   module RubyDesignSystem
     module Inputs
+      # Overrides behaviour of the collection check boxes input in simple_form forms.
+      #
+      # Usage:
+      # Add the following class to the host project at app/inputs/collection_check_boxes_input.rb
+      #
+      #   class CollectionCheckBoxesInput < Barnardos::RubyDesignSystem::Inputs::CollectionCheckBoxesInput; end
+      #
+      # With that in place, the following code will output a set of collection boxes wrapped in the required
+      # Design System components:
+      #
+      #    <%= simple_form_for(foo) do |form| %>
+      #      <%= form.association :bars, as: :check_boxes, wrapper: :in_fieldset, boolean_style: :inline %>
+      #    <% end %>
+      #
+      # Where `foo` has_many `bars`
+      #
       class CollectionCheckBoxesInput < SimpleForm::Inputs::CollectionCheckBoxesInput
         def input(wrapper_options = nil)
           input_html_classes.unshift('Switch-input')

data/lib/barnardos/ruby_design_system/inputs/collection_select_input.rb

@@ -3,6 +3,22 @@
 module Barnardos
   module RubyDesignSystem
     module Inputs
+      # Overrides behaviour of the collection select input in simple_form forms.
+      #
+      # Usage:
+      # Add the following class to the host project at app/inputs/collection_select_input.rb
+      #
+      #   class CollectionSelectInput < Barnardos::RubyDesignSystem::Inputs::CollectionSelectInput; end
+      #
+      # With that in place, the following code will output an HTML select input with class `Select` and wrapped in the
+      # required Design System components:
+      #
+      #    <%= simple_form_for(foo) do |form| %>
+      #      <%= form.association :bars, wrapper: :design_system_select %>
+      #    <% end %>
+      #
+      # Where `foo` has_many `bars`
+      #
       class CollectionSelectInput < SimpleForm::Inputs::CollectionSelectInput
         def input(wrapper_options = nil)
           input_html_classes.unshift('Select')

data/lib/barnardos/ruby_design_system/inputs/string_input.rb

@@ -4,6 +4,22 @@ module Barnardos
   module RubyDesignSystem
     module Inputs
       class StringInput < SimpleForm::Inputs::StringInput
+      # Overrides behaviour of the string input in simple_form forms.
+      #
+      # Usage:
+      # Add the following class to the host project at app/inputs/string_input.rb
+      #
+      #   class StringInput < Barnardos::RubyDesignSystem::Inputs::StringInput; end
+      #
+      # With that in place, the following code will output a text input wrapped in the required
+      # Design System components:
+      #
+      #    <%= simple_form_for(foo) do |form| %>
+      #      <%= form.input :bar %>
+      #    <% end %>
+      #
+      # Where `bar` is a string attribute of `foo`
+      #
         def input(wrapper_options = nil)
           input_html_classes.unshift('TextInput-input')
           super

data/lib/barnardos/ruby_design_system/inputs/text_input.rb

@@ -3,6 +3,22 @@
 module Barnardos
   module RubyDesignSystem
     module Inputs
+      # Overrides behaviour of the text input in simple_form forms.
+      #
+      # Usage:
+      # Add the following class to the host project at app/inputs/text_input.rb
+      #
+      #   class StringInput < Barnardos::RubyDesignSystem::Inputs::TextInput; end
+      #
+      # With that in place, the following code will output a textarea wrapped in the required
+      # Design System components:
+      #
+      #    <%= simple_form_for(foo) do |form| %>
+      #      <%= form.input :bar %>
+      #    <% end %>
+      #
+      # Where `bar` is a text attribute of `foo`
+      #
       class TextInput < SimpleForm::Inputs::TextInput
         def input(wrapper_options = nil)
           input_html_classes.unshift('TextArea-textarea')

data/lib/barnardos/ruby_design_system/version.rb

@@ -1,5 +1,5 @@
 module Barnardos
   module RubyDesignSystem
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/lib/generators/barnardos/install_generator.rb

@@ -21,6 +21,8 @@ module Barnardos
       ].freeze
 
       def install
+        directory 'inputs', 'app/inputs'
+
         `yarn add #{PACKAGES.join(' ')}`
         `yarn add #{DEV_PACKAGES.join(' ')} --dev`
         copy_file 'postcss.config.js', 'postcss.config.js'

data/lib/generators/barnardos/templates/inputs/collection_check_boxes_input.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class CollectionCheckBoxesInput < Barnardos::RubyDesignSystem::Inputs::CollectionCheckBoxesInput
+end

data/lib/generators/barnardos/templates/inputs/collection_select_input.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class CollectionSelectInput < Barnardos::RubyDesignSystem::Inputs::CollectionSelectInput
+end

data/lib/generators/barnardos/templates/inputs/string_input.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class StringInput < Barnardos::RubyDesignSystem::Inputs::StringInput
+end

data/lib/generators/barnardos/templates/inputs/text_input.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class TextInput < Barnardos::RubyDesignSystem::Inputs::TextInput
+end

data/lib/generators/barnardos/templates/postcss.config.js

@@ -1,6 +1,8 @@
 module.exports = () => ({
   plugins: [
     require("postcss-import"),
+    require("postcss-inline-svg"),
+    require("postcss-svgo"),
     require("postcss-preset-env")({
       autoprefixer: {},
       features: {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: barnardos-ruby_design_system
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Rob Nichols
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-22 00:00:00.000000000 Z
+date: 2020-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simple_form
@@ -58,16 +58,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faker
   requirement: !ruby/object:Gem::Requirement
@@ -166,6 +166,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Includes helper methods and modification to simple form.
 email:
 - rob.nichols@barnardos.org.uk
@@ -187,6 +201,10 @@ files:
 - lib/barnardos/ruby_design_system/version.rb
 - lib/generators/barnardos/USAGE
 - lib/generators/barnardos/install_generator.rb
+- lib/generators/barnardos/templates/inputs/collection_check_boxes_input.rb
+- lib/generators/barnardos/templates/inputs/collection_select_input.rb
+- lib/generators/barnardos/templates/inputs/string_input.rb
+- lib/generators/barnardos/templates/inputs/text_input.rb
 - lib/generators/barnardos/templates/postcss.config.js
 homepage: https://design-system.barnardos.org.uk
 licenses: