Class: Primer::BaseComponent

Inherits:
Component
  • Object
show all
Includes:
TestSelectorHelper
Defined in:
app/components/primer/base_component.rb

Overview

All Primer ViewComponents accept a standard set of options called system arguments, mimicking the [styled-system API](styled-system.com/table) used by [Primer React](primer.style/components/system-props).

Under the hood, system arguments are [mapped](github.com/primer/view_components/blob/main/app/lib/primer/classify.rb) to Primer CSS classes, with any remaining options passed to Rails’ [‘content_tag`](api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag).

## Responsive values

To apply different values across responsive breakpoints, pass an array with up to five values in the order ‘[default, small, medium, large, xlarge]`. To skip a breakpoint, pass `nil`.

For example:

“‘erb <%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4, 2]) do %>

Hello world

<% end %> “‘

Renders:

“‘html <h1 class=“mt-0 mt-lg-4 mt-xl-2”>Hello world</h1> “`

## HTML attributes

System arguments include most HTML attributes. For example:

| Name | Type | Description | | :- | :- | :- | | ‘width` | `Integer` | Width. | | `height` | `Integer` | Height. | | `data` | `Hash` | Data attributes: `data: { foo: :bar }` renders `data-foo=’bar’‘. | | `aria` | `Hash` | Aria attributes: `aria: { label: “foo” }` renders `aria-label=’foo’‘. | | `title` | `String` | The `title` attribute. | | `style` | `String` | Inline styles. | | `hidden` | `Boolean` | Whether to assign the `hidden` attribute. |

Constant Summary

Constants included from TestSelectorHelper

TestSelectorHelper::TEST_SELECTOR_TAG

Constants included from Status::Dsl

Status::Dsl::STATUSES

Constants included from ViewHelper

ViewHelper::HELPERS

Constants included from FetchOrFallbackHelper

FetchOrFallbackHelper::InvalidValueError

Instance Method Summary collapse

Methods included from TestSelectorHelper

#add_test_selector

Methods included from JoinStyleArgumentsHelper

#join_style_arguments

Methods included from FetchOrFallbackHelper

#fetch_or_fallback, #fetch_or_fallback_boolean, #silence_deprecations?

Methods included from ClassNameHelper

#class_names

Constructor Details

#initialize(tag:, classes: nil, **system_arguments) ⇒ BaseComponent

Returns a new instance of BaseComponent.

Parameters:

  • test_selector (String) —

    Adds ‘data-test-selector=’given value’‘ in non-Production environments for testing purposes.

  • m (Integer) —

    Margin. <%= one_of((-6..6).to_a) %>

  • mt (Integer) —

    Margin top. <%= one_of((-6..6).to_a) %>

  • mr (Integer) —

    Margin right. <%= one_of((-6..6).to_a) %>

  • mb (Integer) —

    Margin bottom. <%= one_of((-6..6).to_a) %>

  • ml (Integer) —

    Margin left. <%= one_of((-6..6).to_a) %>

  • mx (Integer) —

    Horizontal margins. <%= one_of((-6..6).to_a + [:auto]) %>

  • my (Integer) —

    Vertical margins. <%= one_of((-6..6).to_a) %>

  • p (Integer) —

    Padding. <%= one_of((0..6).to_a) %>

  • pt (Integer) —

    Padding left. <%= one_of((0..6).to_a) %>

  • pr (Integer) —

    Padding right. <%= one_of((0..6).to_a) %>

  • pb (Integer) —

    Padding bottom. <%= one_of((0..6).to_a) %>

  • pl (Integer) —

    Padding left. <%= one_of((0..6).to_a) %>

  • px (Integer) —

    Horizontal padding. <%= one_of((0..6).to_a) %>

  • py (Integer) —

    Vertical padding. <%= one_of((0..6).to_a) %>

  • position (Symbol) —

    <%= one_of([:relative, :absolute, :fixed]) %>

  • top (Boolean) —

    If ‘false`, sets `top: 0`.

  • right (Boolean) —

    If ‘false`, sets `right: 0`.

  • bottom (Boolean) —

    If ‘false`, sets `bottom: 0`.

  • left (Boolean) —

    If ‘false`, sets `left: 0`.

  • display (Symbol) —

    <%= one_of([:none, :block, :flex, :inline, :inline_block, :table, :table_cell]) %>

  • v (Symbol) —

    Visibility. <%= one_of([:hidden, :visible]) %>

  • hide (Symbol) —

    Hide the element at a specific breakpoint. <%= one_of([:sm, :md, :lg, :xl]) %>

  • vertical_align (Symbol) —

    <%= one_of([:baseline, :top, :middle, :bottom, :text_top, :text_bottom]) %>

  • float (Symbol) —

    <%= one_of([:left, :right]) %>

  • col (Integer) —

    Number of columns.

  • underline (Boolean) —

    Whether text should be underlined.

  • color (Symbol) —

    Text color. <br /> <%= one_of(Primer::Classify::FunctionalTextColors::OPTIONS) %> <br /> Deprecated options: <%= one_of(Primer::Classify::FunctionalTextColors::DEPRECATED_OPTIONS) %>

  • bg (String, Symbol) —

    Background color. Accepts either a hex value as a String or a color name as a Symbol.

  • box_shadow (Boolean, Symbol) —

    Box shadow. <%= one_of([true, :medium, :large, :extra_large, :none]) %>

  • border (Symbol) —

    <%= one_of([:left, :top, :bottom, :right, :y, :x, true]) %>

  • border_color (Symbol) —

    <%= one_of(Primer::Classify::FunctionalBorderColors::OPTIONS) %> <br /> Deprecated options: <%= one_of(Primer::Classify::FunctionalBorderColors::DEPRECATED_OPTIONS) %>

  • border_top (Integer) —

    Set to ‘0` to remove the top border.

  • border_bottom (Integer) —

    Set to ‘0` to remove the bottom border.

  • border_left (Integer) —

    Set to ‘0` to remove the left border.

  • border_right (Integer) —

    Set to ‘0` to remove the right border.

  • border_radius (Integer) —

    <%= one_of([0, 1, 2, 3]) %>

  • font_size (String, Integer) —

    <%= one_of([“00”, 0, 1, 2, 3, 4, 5, 6]) %>

  • text_align (Symbol) —

    Text alignment. <%= one_of([:left, :right, :center]) %>

  • font_weight (Symbol) —

    Font weight. <%= one_of([:light, :normal, :bold]) %>

  • flex (Integer, Symbol) —

    <%= one_of([1, :auto]) %>

  • flex_grow (Integer) —

    To enable, set to ‘0`.

  • flex_shrink (Integer) —

    To enable, set to ‘0`.

  • align_self (Symbol) —

    <%= one_of([:auto, :start, :end, :center, :baseline, :stretch]) %>

  • justify_content (Symbol) —

    <%= one_of([:flex_start, :flex_end, :center, :space_between, :space_around]) %>

  • align_items (Symbol) —

    <%= one_of([:flex_start, :flex_end, :center, :baseline, :stretch]) %>

  • width (Symbol) —

    <%= one_of([:fit, :fill]) %>

  • height (Symbol) —

    <%= one_of([:fit, :fill]) %>

  • word_break (Symbol) —

    Whether to break words on line breaks. Can only be ‘:break_all`.

  • animation (Symbol) —

    <%= one_of([:fade_in, :fade_out, :fade_up, :fade_down, :scale_in, :pulse, :grow_x, :grow]) %>

  • tag (Symbol) —

    HTML tag name to be passed to ‘tag.send`.

  • classes (String) (defaults to: nil) —

    CSS class name value to be concatenated with generated Primer CSS classes.



113
114
115
116
117
118
119
 
# File 'app/components/primer/base_component.rb', line 113

def initialize(tag:, classes: nil, **system_arguments)
  @tag = tag
  @result = Primer::Classify.call(**system_arguments.merge(classes: classes))

  # Filter out Primer keys so they don't get assigned as HTML attributes
  @content_tag_args = add_test_selector(system_arguments).except(*Primer::Classify::VALID_KEYS)
end

Instance Method Details

#call ⇒ Object 



121
122
123
 
# File 'app/components/primer/base_component.rb', line 121

def call
  content_tag(@tag, content, @content_tag_args.merge(@result))
end