Class: Primer::Alpha::Overlay

Inherits:
Component
  • Object
show all
Defined in:
app/components/primer/alpha/overlay.rb,
app/components/primer/alpha/overlay/body.rb,
app/components/primer/alpha/overlay/footer.rb,
app/components/primer/alpha/overlay/header.rb

Overview

Overlay components codify design patterns related to floating surfaces such as dialogs and menus. They are private components intended to be used by specialized components, and mostly contain presentational logic and behavior.

Defined Under Namespace

Classes: Body, Footer, Header

Constant Summary collapse

DEFAULT_PADDING = 
:normal
PADDING_MAPPINGS = 
{
  DEFAULT_PADDING => nil,
  :condensed => "Overlay-body--paddingCondensed",
  :none => "Overlay-body--paddingNone"
}.freeze
PADDING_OPTIONS = 
PADDING_MAPPINGS.keys
DEFAULT_SIZE = 
:auto
SIZE_MAPPINGS = 
{
  DEFAULT_SIZE => "Overlay--size-auto",
  :small => "Overlay--size-small",
  :medium => "Overlay--size-medium",
  :medium_portrait => "Overlay--size-medium-portrait",
  :large => "Overlay--size-large",
  :xlarge => "Overlay--size-xlarge"
}.freeze
SIZE_OPTIONS = 
SIZE_MAPPINGS.keys
DEFAULT_ANCHOR_ALIGN = 
:start
ANCHOR_ALIGN_OPTIONS = 
[DEFAULT_ANCHOR_ALIGN, :center, :end].freeze
DEFAULT_ANCHOR_OFFSET = 
:normal
ANCHOR_OFFSET_OPTIONS = 
[DEFAULT_ANCHOR_OFFSET, :spacious].freeze
DEFAULT_ANCHOR_SIDE = 
:outside_bottom
ANCHOR_SIDE_MAPPINGS = 
{
  :inside_top => "inside-top",
  :inside_bottom => "inside-bottom",
  :inside_left => "inside-left",
  :inside_right => "inside-right",
  :inside_center => "inside-center",
  :outside_top => "outside-top",
  DEFAULT_ANCHOR_SIDE => "outside-bottom",
  :outside_left => "outside-left",
  :outside_right => "outside-right"
}.freeze
ANCHOR_SIDE_OPTIONS = 
ANCHOR_SIDE_MAPPINGS.keys
DEFAULT_POPOVER = 
:auto
POPOVER_OPTIONS = 
[DEFAULT_POPOVER, :manual].freeze
ROLE_OPTIONS = 
[:dialog, :menu, nil].freeze
DEFAULT_ALIGN_CONTENT = 
:end
ALIGN_CONTENT_MAPPINGS = 
{
  :start => "Overlay-footer--alignStart",
  :center => "Overlay-footer--alignCenter",
  DEFAULT_ALIGN_CONTENT => "Overlay-footer--alignEnd"
}.freeze
ALIGN_CONTENT_OPTIONS = 
ALIGN_CONTENT_MAPPINGS.keys

Constants inherited from Component

Component::INVALID_ARIA_LABEL_TAGS

Constants included from Status::Dsl

Status::Dsl::STATUSES

Constants included from ViewHelper

ViewHelper::HELPERS

Constants included from TestSelectorHelper

TestSelectorHelper::TEST_SELECTOR_TAG

Constants included from FetchOrFallbackHelper

FetchOrFallbackHelper::InvalidValueError

Constants included from Primer::AttributesHelper

Primer::AttributesHelper::PLURAL_ARIA_ATTRIBUTES, Primer::AttributesHelper::PLURAL_DATA_ATTRIBUTES

Instance Method Summary collapse

Methods inherited from Component

deprecated?, generate_id

Methods included from JoinStyleArgumentsHelper

#join_style_arguments

Methods included from TestSelectorHelper

#add_test_selector

Methods included from FetchOrFallbackHelper

#fetch_or_fallback, #fetch_or_fallback_boolean, #silence_deprecations?

Methods included from ClassNameHelper

#class_names

Methods included from Primer::AttributesHelper

#aria, #data, #merge_aria, #merge_data, #merge_prefixed_attribute_hashes

Constructor Details

#initialize(title:, role: nil, subtitle: nil, popover: DEFAULT_POPOVER, size: DEFAULT_SIZE, padding: DEFAULT_PADDING, anchor: nil, anchor_align: DEFAULT_ANCHOR_ALIGN, anchor_offset: DEFAULT_ANCHOR_OFFSET, anchor_side: DEFAULT_ANCHOR_SIDE, allow_out_of_bounds: false, visually_hide_title: false, id: self.class.generate_id, **system_arguments) ⇒ Overlay

Returns a new instance of Overlay.

Parameters:

  • id (String) (defaults to: self.class.generate_id) —

    The id of the Overlay.

  • title (String) —

    Describes the content of the Overlay.

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

    Provides dditional context for the Overlay, also setting the ‘aria-describedby` attribute.

  • popover (Symbol) (defaults to: DEFAULT_POPOVER) —

    The popover behaviour. <%= one_of(Primer::Alpha::Overlay::POPOVER_OPTIONS) %>

  • size (Symbol) (defaults to: DEFAULT_SIZE) —

    The size of the Overlay. <%= one_of(Primer::Alpha::Overlay::SIZE_OPTIONS) %>

  • padding (Symbol) (defaults to: DEFAULT_PADDING) —

    The padding given to the Overlay body. <%= one_of(Primer::Alpha::Overlay::PADDING_OPTIONS) %>

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

    An ID of the element to anchor onto. Defaults to the ‘show_button`.

  • anchor_align (Symbol) (defaults to: DEFAULT_ANCHOR_ALIGN) —

    The anchor alignment of the Overlay. <%= one_of(Primer::Alpha::Overlay::ANCHOR_ALIGN_OPTIONS) %>

  • anchor_side (Symbol) (defaults to: DEFAULT_ANCHOR_SIDE) —

    The side to anchor the Overlay to. <%= one_of(Primer::Alpha::Overlay::ANCHOR_SIDE_OPTIONS) %>

  • anchor_offset (Symbol) (defaults to: DEFAULT_ANCHOR_OFFSET) —

    The anchor offset to give the Overlay. <%= one_of(Primer::Alpha::Overlay::ANCHOR_OFFSET_OPTIONS) %>

  • allow_out_of_bounds (Boolean) (defaults to: false) —

    Allow the Overlay to overflow its container.

  • visually_hide_title (Boolean) (defaults to: false) —

    If true will hide the heading title, while still making it available to Screen Readers.

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

    The ARIA role. <%= one_of(Primer::Alpha::Overlay::ROLE_OPTIONS) %>

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'app/components/primer/alpha/overlay.rb', line 139

def initialize(
  title:,
  role: nil,
  subtitle: nil,
  popover: DEFAULT_POPOVER,
  size: DEFAULT_SIZE,
  padding: DEFAULT_PADDING,
  anchor: nil,
  anchor_align: DEFAULT_ANCHOR_ALIGN,
  anchor_offset: DEFAULT_ANCHOR_OFFSET,
  anchor_side: DEFAULT_ANCHOR_SIDE,
  allow_out_of_bounds: false,
  visually_hide_title: false,
  id: self.class.generate_id,
  **system_arguments
)
  @system_arguments = deny_tag_argument(**system_arguments)

  @system_arguments[:role] = fetch_or_fallback(ROLE_OPTIONS, role) if role.present?

  @system_arguments[:id] = id.to_s
  @wrapper_classes = class_names(
    "Overlay",
    SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
  )
  @system_arguments[:tag] = "anchored-position"
  @system_arguments[:anchor] = anchor || "overlay-show-#{@system_arguments[:id]}"
  @system_arguments[:align] = fetch_or_fallback(ANCHOR_ALIGN_OPTIONS, anchor_align, DEFAULT_ANCHOR_ALIGN)
  @system_arguments[:side] = ANCHOR_SIDE_MAPPINGS[fetch_or_fallback(ANCHOR_SIDE_OPTIONS, anchor_side, DEFAULT_ANCHOR_SIDE)]
  @system_arguments["anchor-offset"] = fetch_or_fallback(ANCHOR_OFFSET_OPTIONS, anchor_offset, DEFAULT_ANCHOR_OFFSET)
  @system_arguments["allow-out-of-bounds"] = true if allow_out_of_bounds
  @id = id.to_s
  @title = title
  @subtitle = subtitle
  @visually_hide_title = visually_hide_title
  @padding = padding

  @system_arguments[:popover] = popover
  @system_arguments[:aria] ||= {}
end

Instance Method Details

#before_render ⇒ Object 



180
181
182
183
184
185
186
187
188
189
 
# File 'app/components/primer/alpha/overlay.rb', line 180

def before_render
  if @system_arguments[:role].present?
    if header?
      @system_arguments[:aria][:labelledby] ||= title_id
    else
      @system_arguments[:aria][:label] = @title
    end
  end
  with_body unless body?
end