primer_view_components 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8df1dc4f482b73265126a1235b1797912bc6262f1dd3895bb02e95365187cd3a
-  data.tar.gz: 88890fae6a2e9db3fd17d6cb28ba12cfab09ff05d90c04a74012ab013a2b7c21
+  metadata.gz: adc437081b46691abf1c8946de200196e1ceb5b535aa47e7925c03495ae73f3d
+  data.tar.gz: fbbeda9a022db4a9799daf8c0b509481f0ef57c122ac50c51c487a50445a9d65
 SHA512:
-  metadata.gz: 7cdc96278f5790ecd4c6dfcb8dd0ac3cfd9da6255fe1f442070941621af1cb5fd7e321ea7f8782a9be6d8338c01406432747bc7e5b3fc4b605c463d7153000a5
-  data.tar.gz: 269e81f0aa474620d3b6f8398d96bd40bcce8bc11d3c117caea79b46ef1e8158da21f911337386f467145f6263394c01e45cfe58307db52051d04a9e2e22bce4
+  metadata.gz: 648cb2d8145c520fdf7f3da6af9b4047954343d7311caa7b5579adab5dc67b9ca697815e0f0b9c0f9f8d702edd82f9948fbf14ae3ee9397175aa0f3a8d12ec0e
+  data.tar.gz: 90e55106cc699d69f4473cb2844687b4b77597b85c5038be41acf3f56575f0c7e8dbce27ec7fe407b80b91ee12345bc272d2442b84af8ebf837be4451f0983b8

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # main
 
+# 0.0.3
+
+* Add support for responsive `float` style argument.
+
+    *Joel Hawksley*
+
+* Add components:
+    * Avatar
+    * Blankslate
+
+    *Manuel Puyol, Ben Emdon*
+
+# 0.0.1
+
 * Add initial gem configuration.
 
-    *Manuel Puyol, Joel Hawksley*
+    *Manuel Puyol, Joel Hawksley*
+
+* Add demo app and storybook to test
+
+    *Manuel Puyol*
+
+* Add Classify, FetchOrFallback and ClassName helpers
+
+    *Manuel Puyol*
+
+* Add components:
+    * BorderBox
+    * Box
+    * Breadcrumb
+    * Button
+    * Counter
+    * Details
+    * Dropdown
+    * Flex
+    * FlexItem
+    * Heading
+    * Label
+    * Layout
+    * Link
+    * ProgressBar
+    * State
+    * Subhead
+    * Text
+    * TimelineItem
+    * UnderlineNav
+
+    *Manuel Puyol*

data/README.md

@@ -6,6 +6,12 @@
 
 <p align="center">ViewComponents for the Primer Design System</p>
 
+_Note: This library is in pre-release development and should not be considered stable._
+
+## Design philosophy
+
+Primer ViewComponents aims to mimic the API of [Primer Components](https://github.com/primer/components), while using [Primer CSS](https://github.com/primer/css) under the hood.
+
 ## Installation
 
 In `Gemfile`, add:
@@ -14,10 +20,139 @@ In `Gemfile`, add:
 gem "primer_view_components"
 ```
 
+In `config/application.rb`, add **after the application definition**
+
+```ruby
+require "primer/view_components/engine"
+```
+
+## Usage
+
+### Built-in styling arguments
+
+Primer components should be styled using the built-in arguments when possible. Most Primer utility classes for spacing, alignment, display, and colors have equivalent component arguments.
+
+Example label built with Primer CSS:
+
+```html
+<span title="Label: Suggested" class="Label Label--outline Label--outline-green ml-2 v-align-middle">Suggested</span>
+```
+
+The same label using `Primer::LabelComponent`:
+
+```erb
+<%= render Primer::LabelComponent.new(ml: 2, vertical_align: :middle, scheme: :green, title: "Label: Suggested") do %>
+  Suggested
+<% end %>
+```
+
+Some components have their own specific arguments, but they can all be styled with the following arguments.
+
+| Component argument | Primer class    | Example |
+| --------------- | --------------- | -------- |
+| `m`            | `m-<value>`     | `m: 4` → `.m-4` |
+| `my`            | `my-<value>`   | `my: 4` → `.my-4` |
+| `mx`            | `my-<value>`   | `mx: 4` → `.mx-4` |
+| `mt`            | `mt-<value>`   | `mt: 4` → `.mt-4` |
+| `mb`            | `mb-<value>`   | `mb: 4` → `.mb-4` |
+| `ml`            | `ml-<value>`   | `ml: 4` → `.ml-4` |
+| `mr`            | `mr-<value>`   | `mr: 4` → `.mr-4` |
+| `p`             | `p-<value>`    | `p: 4` → `.p-4` |
+| `py`            | `py-<value>`   | `py: 4` → `.py-4` |
+| `px`            | `py-<value>`   | `px: 4` → `.px-4` |
+| `pt`            | `pt-<value>`   | `pt: 4` → `.pt-4` |
+| `pb`            | `pb-<value>`   | `pb: 4` → `.pb-4` |
+| `pl`            | `pl-<value>`   | `pl: 4` → `.pl-4` |
+| `pr`            | `pr-<value>`   | `pr: 4` → `.pr-4` |
+| `pr`            | `pr-<value>`   | `pr: 4` → `.pr-4` |
+| `f`            | `f-<value>`   | `f: 4` → `.f-4` |
+| `color`            | `color-<value>`   | `color: :red_500` → `.color-red-500` |
+| `text`         | `text-<value>`   | `text: :green` → `.text-green` |
+| `bg`         | `bg-<value>`   | `bg: :blue_light` → `.bg-blue-light` |
+| `display`     | `d-<value>` | `display: :none` → `.d-none` |
+| `float`         | `float-<value>`   | `float: :right` → `.float-right` |
+| `vertical_align`         | `v-align-<value>`   | `vertical_align: :baseline` → `.v-align-baseline` |
+| `text_align`     | `text-<value>` | `text_align: :right` → `.text-right` |
+| `font_size`     | `f<value>` | `font_size: 4` → `.f4` |
+| `font_weight`     | `text-<value>` | `font_weight: :bold` → `.text-bold` |
+| `border`     | `border-<value>` | `border: :bottom` → `.border-bottom` |
+| `border_color`     | `border-<value>` | `border: :green` → `.border-green` |
+| `word_break`     | `wb-<value>` | `word_break: :break_all` → `.wb-break-all` |
+| `direction`     | `flex-<value>` | `direction: :row` → `.flex-row` |
+| `justify_content`    | `flex-justify-<value>` | `justify_content: :center` → `.flex-justify-center` |
+| `align_items`   | `flex-items-<value>` | `align_items: :baseline` → `.flex-items-baseline` |
+
+#### Boolean arguments
+| Component arguments | True    | False |
+| -------------- | ------- | ------ |
+| `underline`   | `underline: true` → `.text-underline`  | `underline: false` → `.no-underline` |
+| `top`    | n/a | `top: false` → `.top-0`  |
+| `bottom` | n/a | `bottom: false` → `.bottom-0`  |
+| `left`   | n/a | `left: false` → `.left-0`  |
+| `right`  | n/a | `right: false` → `.right-0`  |
+
+#### Responsive arguments
+
+Different classes can be used for different breakpoints just like in Primer CSS. Simply use an array with the four values required for `[none, small, medium, large]`. If no breakpoint is needed for a breakpoint, pass `nil`.
+
+Example heading built with Primer CSS:
+
+```html
+<h1 class="mt-0 mt-lg-4">Hello world</h1>
+```
+
+The same label using `Primer::HeadingComponent`:
+
+```erb
+<%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4]) do %>
+  Hello world
+<% end %>
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/primer/view_components. 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.
 
+### Setting up
+
+Run
+
+```bash
+script/setup
+```
+
+to install all necessary dependencies
+
+### Storybook
+
+*We recommend having [overmind](https://github.com/DarthSim/overmind) installed to run both rails and storybook, but it is not required.*
+
+To run storybook:
+
+```bash
+script/storybook
+```
+
+### Developing with another app
+
+In your `Gemfile`, change:
+
+```ruby
+gem "primer_view_components"
+```
+
+to
+
+```ruby
+gem "primer_view_components", path: "path_to_the_gem" # e.g. path: "~/primer/view_components"
+```
+
+Then, `bundle install` to update references. You'll now be able to see changes from the gem without having to build it.
+Remember that restarting the Rails server is necessary to see changes, as the gem is loaded at boot time.
+
+To minimize the number of restarts, we recommend checking the component in Storybook first, and then when it's in a good state,
+you can check it in your app.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/components/primer/avatar_component.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Primer
+  class AvatarComponent < Primer::Component
+    SMALL_THRESHOLD = 24
+
+    def initialize(src:, alt:, size: 20, square: false, **kwargs)
+      @kwargs = kwargs
+      @kwargs[:tag] = :img
+      @kwargs[:src] = src
+      @kwargs[:alt] = alt
+      @kwargs[:size] = size
+      @kwargs[:height] = size
+      @kwargs[:width] = size
+
+      @kwargs[:classes] = class_names(
+        "avatar",
+        kwargs[:classes],
+        "avatar--small" => size < SMALL_THRESHOLD,
+        "CircleBadge" => !square
+      )
+    end
+
+    def call
+      render(Primer::BaseComponent.new(**@kwargs)) { content }
+    end
+  end
+end

data/app/components/primer/base_component.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Primer
+  # Base component used by other Primer components.
+  #
+  # tag(symbol): HTML tag name to be passed to tag.send(tag)
+  # class_names(string): CSS class name value to be concatenated with generated Primer CSS classes
+  # args(hash): Combination of arguments for classes_from_hash and content_tag
+  #
+  # Example usage:
+  # <%= render Primer::BaseComponent, tag: :a, href: "http://www.google.com", mt: 4 do %>Link<% end %>
+  # generates:
+  # <a href="http://www.google.com" class="mt-4">Link</a>
+  class BaseComponent < Primer::Component
+    TEST_SELECTOR_TAG = :test_selector
+
+    def initialize(tag:, classes: nil, **args)
+      @tag = tag
+      @result = Primer::Classify.call(**args.merge(classes: classes))
+
+      # Filter out Primer keys so they don't get assigned as HTML attributes
+      @content_tag_args = add_test_selector(args).except(*Primer::Classify::VALID_KEYS)
+    end
+
+    def call
+      tag.public_send(
+        @tag, content, **@content_tag_args.merge(@result)
+      )
+    end
+
+    private
+
+    def add_test_selector(args)
+      if args.key?(TEST_SELECTOR_TAG) && !Rails.env.production?
+        args[:data] ||= {}
+        args[:data][TEST_SELECTOR_TAG] = args[TEST_SELECTOR_TAG]
+      end
+
+      args.except(TEST_SELECTOR_TAG)
+    end
+  end
+end

data/app/components/primer/blankslate_component.html.erb

@@ -0,0 +1,27 @@
+<%= render Primer::BaseComponent.new(**@kwargs) do %>
+  <% if @icon.present? %>
+    <%= octicon @icon, height: @icon_height, class: "blankslate-icon" %>
+  <% end %>
+
+  <% if @image_src.present? && @image_alt.present? %>
+    <%= image_tag "#{@image_src}", class: "mb-3", size: "56x56", alt: "#{@image_alt}" %>
+  <% end %>
+
+  <<%= @title_tag %> class="mb-1"><%= @title %></<%= @title_tag %>>
+
+  <% if @description.present? %>
+    <p><%= @description %></p>
+  <% end %>
+
+  <%= content %>
+
+  <% if @button_text.present? && @button_url.present? %>
+    <p><a class="btn <%= @button_classes %>" href="<%= @button_url %>"><%= @button_text %></a></p>
+  <% end %>
+
+  <% if @link_text.present? && @link_url.present? %>
+    <p class="mt-3">
+      <%= link_to "#{@link_url}" do %><%= @link_text %><% end %>
+    </p>
+  <% end %>
+<% end %>

data/app/components/primer/blankslate_component.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Primer
+  # Blankslates are for when there is a lack of content within a page or section. Use them as placeholders to tell users why something isn't there.
+  #
+  # ## Basic example
+  #
+  # The `Primer::BlankslateComponent` supports the following arguments to add a basic blankslate:
+  #
+  # 1. `title` (`String` required). Text that appears in a larger bold font.
+  # 2. `description` (`String` optional). Text that appears below the title. Typically a whole sentence.
+  #
+  # ```ruby
+  # <%= render Primer::BlankslateComponent.new(
+  #   title: "Title",
+  #   description: "Description",
+  # ) %>
+  # ```
+  #
+  # ## Icon or graphic (optional)
+  #
+  # Add an `icon` to give additional context. Please refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
+  #
+  # ```ruby
+  # <%= render Primer::BlankslateComponent.new(
+  #   icon: "octoface",
+  #   title: "Title",
+  #   description: "Description",
+  # ) %>
+  # ```
+  #
+  # Alternatively you can also add a graphic by providing a path (`image_src`) to an image instead.Also, make sure to add an alternative description (`image_alt`). It will be used for the `alt` tag.
+  #
+  # ```ruby
+  # <%= render Primer::BlankslateComponent.new(
+  #   image_src: "file.svg",
+  #   image_alt: "Description of the image",
+  #   title: "Title",
+  #   description: "Description",
+  # ) %>
+  # ```
+  #
+  # Both icon and graphic will appear above the title.
+  #
+  #
+  # ## Custom content (optional)
+  #
+  # You can add any custom content that typically is used instead of the description:
+  #
+  # ```ruby
+  # <%= render Primer::BlankslateComponent.new(
+  #   icon: "octoface",
+  #   title: "Title",
+  # ) do %>
+  #   <p>Your custom content here</p>
+  # <% end %>
+  # ```
+  #
+  # ## Action button (optional)
+  #
+  # You can provide an action button to help users replace the blankslate. The button will appear below the description and custom content. It takes the following arguments:
+  #
+  # - `button_text` (`String` optional). The text of the button.
+  # - `button_url` (`String` optional). The URL where the user will be taken after clicking the button.
+  #
+  # ```ruby
+  # <%= render Primer::BlankslateComponent.new(
+  #   icon: "book",
+  #   title: "Welcome to the mona wiki!",
+  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+  #
+  #   button_text: "Create the first page",
+  #   button_url: "https://github.com/monalisa/mona/wiki/_new",
+  # ) %>
+  # ```
+  #
+  # ## Link (optional)
+  #
+  # Add an additional link to help users learn more about a feature. The link will be shown at the very bottom:
+  #
+  # - `link_text` (`String` optional). The text of the link.
+  # - `link_url` (`String` optional). The URL where the user will be taken after clicking the link.
+  #
+  # ```ruby
+  # <%= render Primer::BlankslateComponent.new(
+  #   icon: "book",
+  #   title: "Welcome to the mona wiki!",
+  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+  #   button_text: "Create the first page",
+  #   button_url: "https://github.com/monalisa/mona/wiki/_new",
+  #   link_text: "Learn more about wikis",
+  #   link_url: "https://docs.github.com/en/github/building-a-strong-community/about-wikis",
+  # ) %>
+  # ```
+  #
+  # ## Variations (optional)
+  #
+  # There are a few variations of how the Blankslate appears:
+  #
+  # - `narrow` (`Boolean` optional). Adds a maximum width.
+  #
+  # ```ruby
+  # <%= render Primer::BlankslateComponent.new(
+  #   icon: "book",
+  #   title: "Welcome to the mona wiki!",
+  #   description: "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.",
+  #
+  #   narrow: true,
+  # ) %>
+  # ```
+  class BlankslateComponent < Primer::Component
+    def initialize(
+      # required
+      title:,
+
+      # optional
+      title_tag: :h3,
+      icon: "",
+      icon_height: 32,
+      image_src: "",
+      image_alt: " ",
+      description: "",
+      button_text: "",
+      button_url: "",
+      button_classes: "btn-sm btn-primary",
+      link_text: "",
+      link_url: "",
+
+      #variations
+      narrow: false,
+
+      **kwargs
+    )
+      @kwargs = kwargs
+      @kwargs[:tag] = :div
+      @kwargs[:classes] = class_names(
+        @kwargs[:classes],
+        "blankslate",
+        "blankslate-narrow": narrow,
+      )
+
+      @title_tag = title_tag
+      @icon = icon
+      @icon_height = icon_height
+      @image_src = image_src
+      @image_alt = image_alt
+      @title = title
+      @description = description
+      @button_text = button_text
+      @button_url = button_url
+      @button_classes = button_classes
+      @link_text = link_text
+      @link_url = link_url
+    end
+  end
+end