shimmer 0.0.28 → 0.0.30

data/README.md

@@ -4,20 +4,137 @@ Shimmer is a collection of Rails extensions that bring advanced UI features into
 
 ## Features
 
+### Components
+
+Shimmer includes a suite of styled components that can be implemented in React and also in plain HTML or slim.
+
+### Stack
+
+Stack is a reusable typed component that allows you to easily manage the layout of your app. You can define whether it should be displayed horizontally, vertically, and how much spacing there should be in between the child components. This component implements a mobile-first design and allows you to customize the display and spacing even on defined breakpoints (tablet, desktop, widescreen) should you need to.
+
+To use it in a React project, you can just import and use it as you would in a normal React component:
+
+```js
+import { Stack } from "@nerdgeschoss/shimmer/components/stack";
+
+<Stack gapTablet={4} gapDesktop={12} line>
+  <div></div>
+  <div></div>
+  <div></div>
+</Stack>;
+```
+
+To use it in an HTML file, you can just import the css file directly from `@nerdgeschoss/shimmer/components/stack.css` and just implement the classes as they are in the stylesheet:
+
+```html
+<div class="stack stack--line stack--tablet-4 stack--desktop-12">
+  <div></div>
+  <div></div>
+  <div></div>
+</div>
+```
+
+#### Helper types:
+
+```ts
+type Justify =
+  | "start"
+  | "center"
+  | "end"
+  | "space-between"
+  | "space-around"
+  | "stretch"
+  | "equal-size";
+```
+
+```ts
+type Align = "start" | "center" | "end" | "stretch" | "baseline";
+```
+
+![Stack possible layouts](stack.png)
+
+### Available props:
+
+| Field             | Type      | Description                                                                                                                                 |
+| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| gap               | `number`  | Space between elements                                                                                                                      |
+| gapTablet         | `number`  | Gap size for screen starting on Tablet breakpoint                                                                                           |
+| gapDesktop        | `number`  | Gap size for screen starting on Desktop breakpoint                                                                                          |
+| gapWidescreen     | `number`  | Gap size for screen starting on WideScreen breakpoint                                                                                       |
+| line              | `boolean` | Stacks elements horizontally                                                                                                                |
+| lineTablet        | `boolean` | Stacks elements horizontally starting on Tablet breakpoint                                                                                  |
+| lineDesktop       | `boolean` | Stacks elements horizontally starting on Desktop breakpoint                                                                                 |
+| lineWidescreen    | `boolean` | Stacks elements horizontally starting on WideScreen breakpoint                                                                              |
+| align             | `Align`   | Aligns element according to the [main axis](https://developer.mozilla.org/en-US/docs/Glossary/Main_Axis) of the flex container              |
+| alignTablet       | `Align`   | Align on Tablet breakpoint                                                                                                                  |
+| alignDesktop      | `Align`   | Align on Desktop breakpoint                                                                                                                 |
+| alignWidescreen   | `Align`   | Align on Widescreen breakpoint                                                                                                              |
+| justify           | `Justify` | Specifies how elements are distributed along [main axis](https://developer.mozilla.org/en-US/docs/Glossary/Main_Axis) of the flex container |
+| justifyTablet     | `Justify` | Justify on Tablet breakpoint                                                                                                                |
+| justifyDesktop    | `Justify` | Justify on Desktop breakpoint                                                                                                               |
+| justifyWidescreen | `Justify` | Justify on Widescreen breakpoint                                                                                                            |
+
+When using the CSS classes instead of react component we can generate the class names looking at the available props by using the prop names and BEM convention.
+
+For example:
+
+```js
+<Stack gapTablet={4} gapDesktop={12} line>
+  ...
+</Stack>
+```
+
+would translate to
+
+```html
+<div class="stack stack--tablet-4 stack--destop-12 stack--line">...</div>
+```
+
+Pleae, note that there is not word "gap" in the class names since we use it implicitly, i.e. `gapWidescreen={12}` is equivalent to `stack stack--widescreen-12`.
+
+Another thing to keep in mind when using CSS version of the component that the sizes are fixed - in contrary to the React one where we can add any number we want.
+
+Here is the list of available sizes for CSS version:
+
+```scss
+$sizes: (
+  0: 0px,
+  2: 2px,
+  4: 4px,
+  8: 8px,
+  12: 12px,
+  16: 16px,
+  20: 20px,
+  22: 22px,
+  24: 24px,
+  32: 32px,
+  40: 40px,
+  48: 48px,
+  56: 56px,
+  64: 64px,
+);
+```
+
+### Supported breakpoints:
+
+- **Tablet**: 640px
+- **Desktop**: 890px
+- **Widescreen**: 1280px
+
 ### Rubocop Base Configuration
 
-*Shimmer* offers an opiniated *Rubocop* base configuration. This configuration inherits itself from *StandardRB* and aim at remaining as close to it as possible. Why not only use *StandardRB*, since it is so fast and prevent bikeshedding? Well, sadly, it does not solve all problems and using *Rubocop* still integrates a lot easier in most toolsets. However, the idea is to still prevent bikeshedding our *Rubocop* configuration by making sure that every exception to what's configured in *StandardRB* is justified (with a comment over its configuration block in `./config/rubocop_base.yml`), reviewed, debated, and agreed upon before being merged.
+_Shimmer_ offers an opiniated _Rubocop_ base configuration. This configuration inherits itself from _StandardRB_ and aim at remaining as close to it as possible. Why not only use _StandardRB_, since it is so fast and prevent bikeshedding? Well, sadly, it does not solve all problems and using _Rubocop_ still integrates a lot easier in most toolsets. However, the idea is to still prevent bikeshedding our _Rubocop_ configuration by making sure that every exception to what's configured in _StandardRB_ is justified (with a comment over its configuration block in `./config/rubocop_base.yml`), reviewed, debated, and agreed upon before being merged.
 
 #### Use Shared Configuration In Projects
 
-Typically, a `.rubocop.yml` file in projects using *Shimmer* looks like this.
+Typically, a `.rubocop.yml` file in projects using _Shimmer_ looks like this.
 
 ```yml
 inherit_gem:
   shimmer: config/rubocop_base.yml
 ```
 
-Then, if there are specific cops you want to use in the specific project you are working on, you still can easily add them. But at least, the base configuration is shared between projects and is itself as close to *StandardRB* as possible.
+Then, if there are specific cops you want to use in the specific project you are working on, you still can easily add them. But at least, the base configuration is shared between projects and is itself as close to _StandardRB_ as possible.
 
 ### Static File Serving
 
@@ -203,6 +320,30 @@ import { application } from "controllers/application";
 start({ application });
 ```
 
+## Testing & Demo
+
+This library is tested using _RSpec_.
+
+```bash
+bin/rspec
+```
+
+A **system test** suite is included and is performed against a demo _Rails_ application in `spec/rails_app`. This
+application can be started in development mode for "playing around" with _Shimmer_ during its development and add
+more system tests. The `bin/dev` script starts that demo application.
+
+The first time, you want to initialize the database and seed it some data.
+
+```bash
+bin/setup
+```
+
+Then you can start the development server.
+
+```bash
+bin/dev
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/nerdgeschoss/shimmer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nerdgeschoss/shimmer/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+task default: []

data/bin/_guard-core

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application '_guard-core' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("guard", "_guard-core")

data/bin/dev

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+(cd spec/rails_app && bin/dev)

data/bin/guard

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("guard", "guard")

data/bin/rake

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -6,3 +6,6 @@ set -vx
 bundle install
 
 # Do any other automated setup that you need to do here
+
+# Initialize the Rails demo & tests app.
+(cd spec/rails_app && bin/setup)

data/config/rubocop_base.yml

@@ -1,15 +1,11 @@
+# Most of those cops are documented here:
+# https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Style
+#
 AllCops:
   NewCops: disable
-  Exclude:
-    - '**/vendor/bundle/**/*'
-    - '**/bin/**/*'
-    - '**/db/schema.rb'
-    - '**/node_modules/**/*'
 
 require:
-  - standard
-  - rubocop-rails
-  - rubocop-rake
+  - standard # https://github.com/standardrb/standard
 
 inherit_gem:
   standard: config/base.yml
@@ -23,10 +19,32 @@ Style/MutableConstant:
   Enabled: true
   EnforcedStyle: strict
 
-# Allow `.update_all`.
-Rails/SkipsModelValidations:
-  Enabled: false
+# Pass &:method_name as an argument to index_by instead of a block.
+Style/SymbolProc:
+  Enabled: true
+
+# Prefer `[:foo, :bar]` to `%i[foo bar]`.
+Style/SymbolArray:
+  Enabled: true
+  EnforcedStyle: brackets
+
+# Prefer `["foo", "bar"]` to `%w[foo bar]`.
+Style/WordArray:
+  Enabled: true
+  EnforcedStyle: brackets
+
+# <% if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.1") %>
+Style/HashSyntax:
+  Enabled: true
+  EnforcedShorthandSyntax: always
+# <% end %>
 
-# Allow Rake tasks to not require the full Rails app to be loaded.
-Rails/RakeEnvironment:
-  Enabled: false
+# Keep at the end of the file (after the individual cops configuration),
+# otherwise, those cops are not configured properly.
+inherit_from:
+# <% Dir["#{File.expand_path(__dir__)}/rubocop_extensions/*.yml"].each do |filename| %>
+#   <% gem_name = filename.delete_suffix(".yml").delete_prefix("#{File.expand_path(__dir__)}/rubocop_extensions/") %>
+#   <% if Gem.loaded_specs.key?(gem_name) %>
+  - rubocop_extensions/<%= gem_name %>.yml
+#   <% end # if Gem.loaded_specs.key? %>
+# <% end # Dir.foreach %>

data/config/rubocop_extensions/graphql.yml

@@ -0,0 +1,68 @@
+# Documentation on the rules can be found here:
+# https://github.com/DmitryTsepelev/rubocop-graphql/tree/master/lib/rubocop/cop/graphql
+#
+require:
+  - rubocop-graphql
+
+GraphQL:
+  Enabled: false
+
+# Keep mutation file ordered.
+GraphQL/OrderedFields:
+  Enabled: true
+  Exclude:
+    - "*"
+  Include:
+    - '**/mutation_type.rb'
+
+# Ensures snake case of argument name.
+GraphQL/ArgumentName:
+  Enabled: true
+
+# Detects duplicate argument definitions.
+GraphQL/ArgumentUniqueness:
+  Enabled: true
+
+# Prevents defining unnecessary resolver methods in cases when `:hash_key` option can be used.
+GraphQL/FieldHashKey:
+  Enabled: true
+
+# Prevents defining unnecessary resolver methods in cases when `:method option` can be used.
+GraphQL/FieldMethod:
+  Enabled: true
+
+# Ensures snake case of field name.
+GraphQL/FieldName:
+  Enabled: true
+
+# Detects duplicate field definitions within the same type.
+GraphQL/FieldUniqueness:
+  Enabled: true
+
+# Ensures type definitions are class-based (no longer legacy).
+GraphQL/LegacyDsl:
+  Enabled: true
+
+# Ensures fields with multiple definitions are grouped together
+GraphQL/MultipleFieldDefinitions:
+  Enabled: true
+
+# Forces `Relay::Node` implementations to expose an `authorized?` method.
+GraphQL/NotAuthorizedNodeType:
+  Enabled: true
+
+# Checks for has an unnecessary argument camelize.
+GraphQL/UnnecessaryArgumentCamelize:
+  Enabled: true
+
+# Prevents defining an unnecessary `alias`, `method`, or `resolver_method` arguements to fields.
+GraphQL/UnnecessaryFieldAlias:
+  Enabled: true
+
+# Checks for has an unnecessary field camelize.
+GraphQL/UnnecessaryFieldCamelize:
+  Enabled: true
+
+# Arguments should either be listed explicitly or `**rest` should be in the resolve signature.
+GraphQL/UnusedArgument:
+  Enabled: true

data/config/rubocop_extensions/rails.yml

@@ -0,0 +1,34 @@
+AllCops:
+  Exclude:
+    - '**/vendor/bundle/**/*'
+    - '**/db/schema.rb'
+
+require:
+  - rubocop-rails
+
+Rails:
+  Enabled: false
+
+# Prefer :bad_request over 400 to define HTTP status code.
+Rails/HttpStatus:
+  Enabled: true
+
+# Prefer index_by over map { ... }.to_h.
+Rails/IndexBy:
+  Enabled: true
+
+# Prefer index_with over each_with_object.
+Rails/IndexWith:
+  Enabled: true
+
+# Specify a :dependent option. (https://rails.rubystyle.guide#has_many-has_one-dependent-option)
+Rails/HasManyOrHasOneDependent:
+  Enabled: true
+
+# Specify an :inverse_of option.
+Rails/InverseOf:
+  Enabled: true
+
+# Specifying the default value for foreign_key is redundant.
+Rails/RedundantForeignKey:
+  Enabled: true

data/config/rubocop_extensions/rspec.yml

@@ -0,0 +1,203 @@
+require:
+  - rubocop-rspec
+
+RSpec:
+  Enabled: false
+
+# Checks that around blocks actually run the test.
+# Would be a shame if the test would be green simply because it is not called.
+RSpec/AroundBlock:
+  Enabled: true
+
+# Be what? Not nil? Present? Truthy?
+RSpec/Be:
+  Enabled: true
+
+# The be matcher compares by identity while the eq matcher compares using ==.
+# Booleans and nil can be compared by identity and therefore the be matcher is
+# preferable as it is a more strict test.
+RSpec/BeEq:
+  Enabled: true
+
+# The be matcher compares by identity while the eq matcher compares using ==.
+# Booleans and nil can be compared by identity and therefore the be matcher is
+# preferable as it is a more strict test.
+RSpec/BeEql:
+  Enabled: true
+
+# Prefer `.to be_nil` to `.to be(nil)`.
+RSpec/BeNil:
+  Enabled: true
+
+# Avoid `before(:all)`, prefer `before(:each)` within a group.
+RSpec/BeforeAfterAll:
+  Enabled: true
+
+# Avoid `.to change(...).by(0)`, prefer `not_to change` and `.to not_change` (for composite).
+RSpec/ChangeByZero:
+  Enabled: true
+
+# Expect expectations in all tests.
+# If it's just expecting it to not raise, wrap it in `expect do ... end.not_to raise`.
+RSpec/EmptyExampleGroup:
+  Enabled: true
+
+# Don't allow empty hooks.
+RSpec/EmptyHook:
+  Enabled: true
+
+# Separate groups.
+RSpec/EmptyLineAfterExampleGroup:
+  Enabled: true
+
+# Separate `let`s from tests.
+RSpec/EmptyLineAfterFinalLet:
+  Enabled: true
+
+# Separate hooks from tests.
+RSpec/EmptyLineAfterHook:
+  Enabled: true
+
+# Don't allow specs without description.
+RSpec/ExampleWithoutDescription:
+  Enabled: true
+
+# Checks for common mistakes in example descriptions.
+RSpec/ExampleWording:
+  Enabled: true
+
+# Trim descriptions.
+RSpec/ExcessiveDocstringSpacing:
+  Enabled: true
+
+# Do stdout expectations right.
+RSpec/ExpectOutput:
+  Enabled: true
+
+# Enforces spec file naming convention.
+RSpec/FilePath:
+  Enabled: true
+
+# Don't forget focussed tests (expecially useful for the CI to fail).
+RSpec/Focus:
+  Enabled: true
+  AutoCorrect: false
+
+# Checks for before/around/after hooks that come after an example.
+RSpec/HooksBeforeExamples:
+  Enabled: true
+
+# Don't expect something to be itself.
+RSpec/IdenticalEqualityAssertion:
+  Enabled: true
+
+# Explicitly declare `it` blocks.
+RSpec/ImplicitBlockExpectation:
+  Enabled: true
+
+# Prevent instance variable usage in specs.
+RSpec/InstanceVariable:
+  Enabled: true
+
+# Check that all matcher is used instead of iterating over an array.
+RSpec/IteratedExpectation:
+  Enabled: true
+
+# Checks that no class, module, or constant is declared.
+# Constants, including classes and modules, when declared in a block scope,
+# are defined in global namespace, and leak between examples.
+# Prevents class re-opening, leading to unpredictable side effects.
+RSpec/LeakyConstantDeclaration:
+  Enabled: true
+
+# Force `let`s to be before tests.
+RSpec/LetBeforeExamples:
+  Enabled: true
+
+# Force groups to have descriptions or symbol.
+RSpec/MissingExampleGroupArgument:
+  Enabled: true
+
+# Files should have only one root `describe` block.
+RSpec/MultipleDescribes:
+  Enabled: true
+
+# Checks if an example group defines subject multiple times.
+RSpec/MultipleSubjects:
+  Enabled: true
+
+# Checks if an example contains any expectation.
+RSpec/NoExpectationExample:
+  Enabled: false # considered, but gives false positives when expectations are inside of a re-used function
+
+# Prefer `expect(...).not_to` to `expect(...).to_not`.
+RSpec/NotToNot:
+  Enabled: true
+
+# Prevent setting the same `let` block more than once.
+RSpec/OverwritingSetup:
+  Enabled: true
+
+# Prevent useless `around` hooks.
+RSpec/RedundantAround:
+  Enabled: true
+
+# Prevent duplicate description.
+RSpec/RepeatedDescription:
+  Enabled: true
+
+# Prevent duplicate example (test).
+RSpec/RepeatedExample:
+  Enabled: true
+
+# Detects duplicate in example group body.
+RSpec/RepeatedExampleGroupBody:
+  Enabled: true
+
+# Detects duplicate in example group description.
+RSpec/RepeatedExampleGroupDescription:
+  Enabled: true
+
+# Check for repeated include of shared examples.
+RSpec/RepeatedIncludeExample:
+  Enabled: true
+
+# Keep `let` blocks together.
+RSpec/ScatteredLet:
+  Enabled: true
+
+# Keep `setup` blocks (ex: group `before`) together.
+RSpec/ScatteredSetup:
+  Enabled: true
+
+# Checks for proper shared_context and shared_examples usage.
+RSpec/SharedContext:
+  Enabled: true
+
+# Enforces use of string to titleize shared examples.
+RSpec/SharedExamples:
+  Enabled: true
+
+# Checks that chains of messages contain more than one element.
+RSpec/SingleArgumentMessageChain:
+  Enabled: true
+
+# Skip either the whole example of not at all.
+RSpec/SkipBlockInsideExample:
+  Enabled: true
+
+# Be specific about what exception/error is expected.
+RSpec/UnspecifiedException:
+  Enabled: true
+
+# Use symbols for `let` and `subject` names.
+RSpec/VariableDefinition:
+  Enabled: true
+
+# Avoid empty expectation.
+RSpec/VoidExpect:
+  Enabled: true
+
+# Use proper `yield` stub syntax.
+RSpec/Yield:
+  Enabled: true