ariadne_view_components 0.0.1

data/app/components/ariadne/flash_component.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Ariadne
+  # Use `FlashComponent` to inform users of successful messages, pending actions, or urgent notices.
+  class FlashComponent < Ariadne::Component
+    include IconHelper
+
+    DEFAULT_SCHEME = :default
+
+    DISMISSIBLE_SCHEME_CLASS_MAPPINGS = {
+      default: "text-blue-500 bg-blue-50 hover:bg-blue-100 focus:ring-offset-blue-50 focus:ring-blue-600",
+      info: "text-blue-500 bg-blue-50 hover:bg-blue-100 focus:ring-offset-blue-50 focus:ring-blue-600",
+      success: "text-green-500 bg-green-50 hover:bg-green-100 focus:ring-offset-green-50 focus:ring-green-600",
+      warning: "text-yellow-500 bg-yellow-50 hover:bg-yellow-100 focus:ring-offset-yellow-50 focus:ring-yellow-600",
+      danger: "text-red-500 bg-red-50 hover:bg-red-100 focus:ring-offset-red-50 focus:ring-red-600",
+    }.freeze
+    VALID_DISMISSIBLE_SCHEMES = DISMISSIBLE_SCHEME_CLASS_MAPPINGS.keys.freeze
+
+    BG_SCHEME_CLASS_MAPPINGS = {
+      default: "bg-blue-50",
+      info: "bg-blue-50",
+      success: "bg-green-50",
+      warning: "bg-yellow-50",
+      danger: "bg-red-50",
+    }.freeze
+    VALID_BG_SCHEMES = BG_SCHEME_CLASS_MAPPINGS.keys.freeze
+
+    CONTENT_SCHEME_CLASS_MAPPINGS = {
+      default: "text-blue-700",
+      info: "text-blue-700",
+      success: "text-green-700",
+      warning: "text-yellow-700",
+      danger: "text-red-700",
+    }.freeze
+    VALID_CONTENT_SCHEMES = CONTENT_SCHEME_CLASS_MAPPINGS.keys.freeze
+
+    # Optional visuals appearing to the left of the flash banner.
+    #
+    # Use:
+    #
+    # - `icon` for a <%= link_to_component(Ariadne::HeroiconComponent) %>.
+    #
+    # @option params [Symbol] :icon The rendered tag name
+    # @option params [Symbol] :icon Name of <%= link_to_heroicons %> to use.
+    # @option params [Symbol] :variant <%= one_of(HeroiconsHelper::Icon::VARIANTS, sort: false) %>
+    # @option params [String] :classes  <%= link_to_classes_docs %>
+    # @option params [Hash] :attributes Same arguments as <%= link_to_component(Ariadne::HeroiconComponent) %>.
+    renders_one :icon, lambda { |tag: :svg, icon:, variant:, classes: "", attributes: {}|
+                         @icon = icon
+                         @variant = variant
+
+                         tag = check_incoming_tag(:svg, tag)
+                         Ariadne::HeroiconComponent.new(tag: tag, icon: icon, variant: variant, classes: classes, attributes: attributes)
+                       }
+
+    # Optional action content showed at the bottom of the component.
+    #
+    # @param tag [Symbol, String] The rendered tag name
+    # @param classes [String] <%= link_to_classes_docs %>
+    # @param attributes [Hash] <%= link_to_attributes_docs %>
+    renders_one :action, lambda { |tag: :div, classes: "", attributes: {}|
+      tag = check_incoming_tag(:div, tag)
+
+      actual_classes = class_names(classes)
+
+      Ariadne::BaseComponent.new(tag: tag, classes: actual_classes, attributes: attributes)
+    }
+
+    # @example Schemes
+    #   <%= render(Ariadne::FlashComponent.new) { "This is a flash message!" } %>
+    #   <%= render(Ariadne::FlashComponent.new(scheme: :warning)) { "This is a warning flash message!" } %>
+    #   <%= render(Ariadne::FlashComponent.new(scheme: :danger)) { "This is a danger flash message!" } %>
+    #   <%= render(Ariadne::FlashComponent.new(scheme: :success)) { "This is a success flash message!" } %>
+    #
+    # @example Dismissible
+    #   <%= render(Ariadne::FlashComponent.new(dismissible: true)) { "This is a dismissible flash message!" } %>
+    #
+    # @example Icon
+    #   <%= render(Ariadne::FlashComponent.new) do |component| %>
+    #     <% component.icon(icon: :"user-group", variant: HeroiconsHelper::Icon::VARIANT_OUTLINE) %>
+    #     Look at this icon.
+    #   <% end %>
+    #
+    # @example With actions
+    #   <%= render(Ariadne::FlashComponent.new) do |component| %>
+    #     <% component.action do %>
+    #       <%= render(Ariadne::ButtonComponent.new(size: :s)) { "Take action" } %>
+    #     <% end %>
+    #     This is a flash message with actions!
+    #   <% end %>
+    #
+    # @param tag [Symbol, String] The rendered tag name.
+    # @param dismissible [Boolean] Whether the component can be dismissed with an X button.
+    # @param icon [Symbol, String] Name of <%= link_to_heroicons %> to use.
+    # @param scheme [Symbol] <%= one_of(Ariadne::FlashComponent::VALID_CONTENT_SCHEMES) %>
+    # @param classes [String] <%= link_to_classes_docs %>
+    # @param attributes [Hash] <%= link_to_attributes_docs %>
+    def initialize(tag: :div, dismissible: false, scheme: DEFAULT_SCHEME, classes: "", attributes: {})
+      @dismissible = dismissible
+
+      @tag = check_incoming_tag(:div, tag)
+
+      @scheme = fetch_or_raise(VALID_CONTENT_SCHEMES, scheme)
+
+      @classes = class_names(
+        CONTENT_SCHEME_CLASS_MAPPINGS[@scheme],
+        classes
+      )
+
+      @attributes = attributes
+    end
+
+    private def has_action?
+      action.present?
+    end
+
+    private def dismissible?
+      @dismissible.present?
+    end
+
+    private def dismissible_classes
+      DISMISSIBLE_SCHEME_CLASS_MAPPINGS[@scheme]
+    end
+  end
+end

data/app/components/ariadne/heading_component.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Ariadne
+  # `Heading` should be used to communicate page organization and hierarchy.
+  #
+  # - Set tag to one of `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, `:h6` based on what is appropriate for the page context.
+  # - Use `Heading` as the title of a section or sub section.
+  # - Do not use `Heading` for styling alone. For simply styling text, consider using <%= link_to_component(Ariadne::Text) %> with relevant <%= link_to_typography_docs %>
+  #   such as `font_size` and `font_weight`.
+  # - Do not jump heading levels. For instance, do not follow a `<h1>` with an `<h3>`. Heading levels should increase by one in ascending order.
+  #
+  # @accessibility
+  #   While sighted users rely on visual cues such as font size changes to determine what the heading is, assistive technology users rely on programatic cues that can be read out.
+  #   When text on a page is visually implied to be a heading, ensure that it is coded as a heading. Additionally, visually implied heading level and coded heading level should be
+  #   consistent. [See WCAG success criteria: 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)
+  #
+  #   Headings allow assistive technology users to quickly navigate around a page. Navigation to text that is not meant to be a heading can be a confusing experience.
+  #   <%= link_to_heading_practices %>
+  class HeadingComponent < Ariadne::Component
+    TAG_OPTIONS = [:h1, :h2, :h3, :h4, :h5, :h6].freeze
+
+    TAG_TO_CLASSES = {
+      h1: "font-bold leading-7 sm:text-3xl sm:truncate",
+      h2: "text-3xl font-extrabold text-gray-900",
+      h3: "text-2xl font-extrabold text-gray-900",
+    }
+    # @example Default
+    #   <%= render(Ariadne::HeadingComponent.new(tag: :h1)) { "H1 Text" } %>
+    #   <%= render(Ariadne::HeadingComponent.new(tag: :h2)) { "H2 Text" } %>
+    #   <%= render(Ariadne::HeadingComponent.new(tag: :h3)) { "H3 Text" } %>
+    #   <%= render(Ariadne::HeadingComponent.new(tag: :h4)) { "H4 Text" } %>
+    #   <%= render(Ariadne::HeadingComponent.new(tag: :h5)) { "H5 Text" } %>
+    #   <%= render(Ariadne::HeadingComponent.new(tag: :h6)) { "H6 Text" } %>
+    #
+    # @param tag [String]  <%= one_of(Ariadne::HeadingComponent::TAG_OPTIONS) %>
+    # @param classes [String] <%= link_to_classes_docs %>
+    # @param attributes [Hash] <%= link_to_attributes_docs %>
+    def initialize(tag: nil, classes: "", attributes: {})
+      @tag = fetch_or_raise(TAG_OPTIONS, tag)
+      @attributes = attributes
+
+      @classes = class_names(*TAG_TO_CLASSES[tag], classes)
+    end
+
+    def call
+      render(Ariadne::BaseComponent.new(tag: @tag, classes: @classes, attributes: @attributes)) { content }
+    end
+  end
+end

data/app/components/ariadne/heroicon_component.html.erb

@@ -0,0 +1,7 @@
+<%= render(Ariadne::BaseComponent.new(tag: @tag, classes: @classes, attributes: @attributes)) do %>
+  <% if @use_symbol %>
+    <use href="#heroicon_<%= [@icon.symbol, @icon.height].join("_") %>"></use>
+  <% else %>
+    <%= @icon.path.html_safe %>
+  <% end %>
+<% end %>

data/app/components/ariadne/heroicon_component.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "heroicons_helper"
+
+module Ariadne
+  # `Heroicon` renders an <%= link_to_heroicons %> with <%= link_to_attributes_docs %>.
+  # `Heroicon` can also be rendered with the `heroicon` helper.
+  class HeroiconComponent < Ariadne::Component
+    include IconHelper
+    include HeroiconsHelper
+
+    SIZE_DEFAULT = :small
+    SIZE_MEDIUM = :medium
+
+    SIZE_MAPPINGS = {
+      SIZE_DEFAULT => 16,
+      SIZE_MEDIUM => 24,
+    }.freeze
+    SIZE_OPTIONS = SIZE_MAPPINGS.keys
+
+    PRELOADED_ICONS = [
+      { name: "bell",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "check",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "chevron-down",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "clipboard",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "clock",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "information-circle",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "dots-horizontal",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "link",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "lock-closed",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "mail",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "pencil",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "plus-sm",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "question-mark-circle",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "search",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "search",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "trash",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+      { name: "x",
+        variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, },
+    ].freeze
+
+    # @example Default
+    #   <%= render(Ariadne::HeroiconComponent.new(icon: :check, variant: HeroiconsHelper::Icon::VARIANT_OUTLINE)) %>
+    #   <%= render(Ariadne::HeroiconComponent.new(icon: :check, variant: HeroiconsHelper::Icon::VARIANT_SOLID)) %>
+    #
+    # @example Medium
+    #   <%= render(Ariadne::HeroiconComponent.new(icon: :"user-group", variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, size: :medium)) %>
+    #
+    # @example Helper
+    #   <%= ariadne_heroicon(icon: :check, variant: HeroiconsHelper::Icon::VARIANT_OUTLINE) %>
+    #
+    # @param tag [Symbol, String] The rendered tag name
+    # @param classes [String] <%= link_to_classes_docs %>
+    # @param icon [Symbol, String] Name of <%= link_to_heroicons %> to use.
+    # @param variant [String] <%= one_of(HeroiconsHelper::Icon::VARIANTS, sort: false) %>
+    # @param size [Symbol] <%= one_of(Ariadne::HeroiconComponent::SIZE_MAPPINGS, sort: false) %>
+    # @param attributes [Hash] <%= link_to_attributes_docs %>
+    def initialize(tag: :svg, icon:, variant:, size: SIZE_DEFAULT, classes: "", attributes: {})
+      @tag = check_incoming_tag(:svg, tag)
+
+      check_icon_presence!(icon, variant)
+
+      @attributes = attributes
+      @attributes[:aria] ||= {}
+
+      if @attributes[:aria][:label] || @attributes[:"aria-label"]
+        @attributes[:role] = "img"
+      else
+        @attributes[:aria][:hidden] = true
+      end
+
+      # Don't allow sizes under 16px
+      if attributes[:height].present? && attributes[:height].to_i < 16 || attributes[:width].present? && attributes[:width].to_i < 16
+        attributes.delete(:height)
+        attributes.delete(:width)
+      end
+
+      # Filter out classify options to prevent them from becoming invalid html attributes.
+      # Note height and width are both classify options and valid html attributes.
+      attributes = {
+        height: @attributes[:height] || SIZE_MAPPINGS[fetch_or_raise(SIZE_OPTIONS, size)],
+        width: @attributes[:width],
+      }
+
+      @icon = heroicon(icon, variant: variant, **attributes) # rubocop:disable Ariadne/AriadneHeroicon
+
+      @classes = class_names(
+        @icon.attributes[:class],
+        classes
+      )
+      @attributes.merge!(@icon.attributes.except(:class, :"aria-hidden"))
+    end
+
+    def self._after_compile
+      HeroiconsHelper::Cache.preload!(PRELOADED_ICONS) do |found, icon|
+        HeroiconComponent.new(icon: icon[:name], variant: icon[:variant]) unless found
+      end
+    end
+  end
+end

data/app/components/ariadne/image_component.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ariadne
+  # Use `Image` to render images.
+  #
+  # @accessibility
+  #   Always provide a meaningful `alt`.
+  class ImageComponent < Ariadne::Component
+    # @example Default
+    #
+    #   <%= render(Ariadne::ImageComponent.new(src: "https://github.com/github.png", alt: "GitHub")) %>
+    #
+    # @example Helper
+    #
+    #   <%= ariadne_image(src: "https://github.com/github.png", alt: "GitHub") %>
+    #
+    # @example Lazy loading
+    #
+    #   <%= render(Ariadne::ImageComponent.new(src: "https://github.com/github.png", alt: "GitHub", lazy: true)) %>
+    #
+    # @example Custom size
+    #
+    #   <%= render(Ariadne::ImageComponent.new(src: "https://github.com/github.png", alt: "GitHub", attributes: { height: 100, width: 100 })) %>
+    #
+    # @param tag [Symbol, String] The rendered tag name
+    # @param classes [String] <%= link_to_classes_docs %>
+    # @param src [String] The source url of the image.
+    # @param alt [String] Specifies an alternate text for the image.
+    # @param lazy [Boolean] Whether or not to lazily load the image.
+    # @param attributes [Hash] <%= link_to_attributes_docs %>
+    def initialize(tag: :img, src:, alt:, lazy: false, classes: "", attributes: {})
+      @attributes = attributes
+
+      @src = src
+      @tag = check_incoming_tag(:img, tag)
+      @classes = classes
+
+      @attributes[:alt] = alt
+      @attributes[:src] = image_path(@src)
+
+      return unless lazy
+
+      @attributes[:loading] = :lazy
+      @attributes[:decoding] = :async
+    end
+
+    def call
+      render(Ariadne::BaseComponent.new(tag: @tag, classes: @classes, attributes: @attributes))
+    end
+  end
+end

data/app/components/ariadne/text.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ariadne
+  # `Text` is a wrapper component that will apply typography styles to the text inside.
+  class Text < Ariadne::Component
+    DEFAULT_TAG = :span
+
+    # @example Default
+    #   <%= render(Ariadne::Text.new(tag: :p, attributes: { font_weight: :bold })) { "Bold Text" } %>
+    #   <%= render(Ariadne::Text.new(tag: :p, attributes: { color: :danger })) { "Danger Text" } %>
+    #
+    # @param tag [Symbol, String] The rendered tag name
+    # @param classes [String] <%= link_to_classes_docs %>
+    # @param attributes [Hash] <%= link_to_attributes_docs %>
+    def initialize(tag: DEFAULT_TAG, classes: "", attributes: {})
+      @tag = tag
+      @classes = classes
+      @attributes = attributes
+    end
+
+    def call
+      render(Ariadne::BaseComponent.new(tag: @tag, classes: @classes, attributes: @attributes)) { content }
+    end
+  end
+end

data/app/components/ariadne/tooltip_component.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Ariadne
+  # `Tooltip` only appears on mouse hover or keyboard focus and contain a label or description text.
+  # Use tooltips sparingly and as a last resort.
+  #
+  # When using a tooltip, follow the provided guidelines to avoid accessibility issues.
+  #
+  # - Tooltip text should be brief and to the point. The tooltip content must be a string.
+  # - Tooltips should contain only **non-essential text**. Tooltips can easily be missed and are not accessible on touch devices so never
+  #  use tooltips to convey critical information.
+  #
+  # @accessibility
+  #   - **Never set tooltips on static elements.** Tooltips should only be used on interactive elements like buttons or links to avoid excluding keyboard-only users
+  #   and screen reader users.
+  #   - Place `Tooltip` adjacent after its trigger element in the DOM. This allows screen reader users to navigate to and copy the tooltip
+  #   content.
+  #   ### Which `type` should I set?
+  #   Setting `:description` establishes an `aria-describedby` relationship, while `:label` establishes an `aria-labelledby` relationship between the trigger element and the tooltip,
+  #
+  #   The `type` drastically changes semantics and screen reader behavior so follow these guidelines carefully:
+  #   - When there is already a visible label text on the trigger element, the tooltip is likely intended to supplement the existing text, so set `type: :description`.
+  #   The majority of tooltips will fall under this category.
+  #   - When there is no visible text on the trigger element and the tooltip content is appropriate as a label for the element, set `type: :label`.
+  #   This type is usually only appropriate for an icon-only control.
+  class TooltipComponent < Ariadne::Component
+    DIRECTION_DEFAULT = :s
+    DIRECTION_OPTIONS = [DIRECTION_DEFAULT, :n, :e, :w, :ne, :nw, :se, :sw].freeze
+
+    TYPE_DEFAULT = :description
+    TYPE_OPTIONS = [:label, TYPE_DEFAULT].freeze
+    # @example As a description for an icon-only button
+    #   @description
+    #     If the tooltip content provides supplementary description, set `type: :description` to establish an `aria-describedby` relationship.
+    #     The trigger element should also have a _concise_ accessible label via `aria-label`.
+    #   @code
+    #     <%= render(Ariadne::HeroiconComponent.new(icon: :moon, variant: HeroiconsHelper::Icon::VARIANT_OUTLINE, attributes: { id: "bold-button-0" })) %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for: "bold-button-0" }, type: :description, text: "Add bold text", direction: :ne)) %>
+    # @example As a label for an icon-only button
+    #   @description
+    #     If the tooltip labels the icon-only button, set `type: :label`. This tooltip content becomes the accessible name for the button.
+    #   @code
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "like-button"})) { "👍" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "like-button" }, type: :label, text: "Like", direction: :n)) %>
+    #
+    # @example As a description for a button with visible label
+    #   @description
+    #     If the button already has visible label text, the tooltip content is likely supplementary so set `type: :description`.
+    #   @code
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "save-button"}, scheme: :success)) { "Save" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "save-button"}, type: :description, text: "This will immediately impact all organization members", direction: :ne)) %>
+    # @example With direction
+    #   @description
+    #     Set direction of tooltip with `direction`. The tooltip is responsive and will automatically adjust direction to avoid cutting off.
+    #   @code
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "North", m: 2})) { "North" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "North"}, type: :description, text: "This is a North-facing tooltip, and is responsive.", direction: :n)) %>
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "South", m: 2})) { "South" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "South"}, type: :description, text: "This is a South-facing tooltip and is responsive.", direction: :s)) %>
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "East", m: 2})) { "East" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "East"}, type: :description, text: "This is a East-facing tooltip and is responsive.", direction: :e)) %>
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "West", m: 2})) { "West" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "West"}, type: :description, text: "This is a West-facing tooltip and is responsive.", direction: :w)) %>
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "Northeast", m: 2})) { "Northeast" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "Northeast"}, type: :description, text: "This is a Northeast-facing tooltip and is responsive.", direction: :ne)) %>
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "Southeast", m: 2})) { "Southeast" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "Southeast"}, type: :description, text: "This is a Southeast-facing tooltip and is responsive.", direction: :se)) %>
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "Northwest", m: 2})) { "Northwest" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "Northwest"}, type: :description, text: "This is a Northwest-facing tooltip and is responsive.", direction: :nw)) %>
+    #     <%= render(Ariadne::ButtonComponent.new(attributes: {id: "Southwest", m: 2})) { "Southwest" } %>
+    #     <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "Southwest"}, type: :description, text: "This is a Southwest-facing tooltip and is responsive.", direction: :sw)) %>
+    # @example With relative parent
+    #   @description
+    #     When the tooltip and trigger element have a parent container with `relative: position`, it should not affect width of the tooltip.
+    #   @code
+    #     <span style="position: relative;">
+    #       <%= render(Ariadne::ButtonComponent.new(attributes: {id: "test-button"}, scheme: :info)) { "Test" } %>
+    #       <%= render(Ariadne::TooltipComponent.new(attributes: { for:  "test-button" }, type: :description, text: "This tooltip should take up the full width", direction: :ne)) %>
+    #     </span>
+    # @param tag [Symbol, String] The rendered tag name
+    # @param type [Symbol] <%= one_of(Ariadne::TooltipComponent::TYPE_OPTIONS) %>
+    # @param text [String] The text content of the tooltip. This should be brief and no longer than a sentence.
+    # @param direction [Symbol] <%= one_of(Ariadne::TooltipComponent::DIRECTION_OPTIONS) %>
+    # @param classes [String] <%= link_to_classes_docs %>
+    # @param attributes [Hash] <%= link_to_attributes_docs %>
+    def initialize(tag: :"tool-tip", type: TYPE_DEFAULT, text:, direction: DIRECTION_DEFAULT, classes: "", attributes: {})
+      raise TypeError, "tooltip text must be a string" unless text.is_a?(String)
+
+      @tag = check_incoming_tag(:"tool-tip", tag)
+
+      @text = text
+      @classes = classes
+
+      @attributes = attributes
+      @attributes[:hidden] = true
+      @attributes[:visible] ||= false
+      @attributes[:"data-direction"] = fetch_or_raise(DIRECTION_OPTIONS, direction)
+      @attributes[:"data-type"] = fetch_or_raise(TYPE_OPTIONS, type)
+    end
+
+    def call
+      render(Ariadne::BaseComponent.new(tag: @tag, classes: @classes, attributes: @attributes)) { @text }
+    end
+  end
+end

data/app/lib/ariadne/audited/dsl.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Ariadne
+  # :nodoc:
+  module Audited
+    # DSL to register when a component has passed an accessibility audit.
+    #
+    # Example:
+    #
+    # class MyComponent < ViewComponent::Base
+    #   include Ariadne::Audited::Dsl
+    #   audited_at 'YYYY-MM-DD'
+    # end
+    module Dsl
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :audit_date, instance_writer: false
+      end
+
+      class_methods do
+        def audited_at(date = nil)
+          return audit_date if date.nil?
+
+          self.audit_date = date
+        end
+      end
+    end
+  end
+end

data/app/lib/ariadne/class_name_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Helps build a list of conditional class names
+module Ariadne
+  # :nodoc:
+  module ClassNameHelper
+    def class_names(*args)
+      [].tap do |classes|
+        args.each do |class_name|
+          next if class_name.blank?
+
+          case class_name
+          when String
+            classes << class_name
+          else
+            raise ArgumentError, "Expected String class name, got #{class_name.class}"
+          end
+        end
+      end.join(" ")
+    end
+  end
+end

data/app/lib/ariadne/fetch_or_fallback_helper.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Ariadne::FetchOrFallbackHelper
+# A little helper to enable graceful fallbacks
+#
+# Use this helper to quietly ensure a value is
+# one that you expect:
+#
+# allowed_values    - allowed options for *value*
+# given_value       - input being coerced
+# fallback          - returned if *given_value* is not included in *allowed_values*
+#
+# fetch_or_raise([1,2,3], 5) => 2
+# fetch_or_raise([1,2,3], 1) => 1
+# fetch_or_raise([1,2,3], nil) => 2
+module Ariadne
+  # :nodoc:
+  module FetchOrFallbackHelper
+    include LoggerHelper
+
+    mattr_accessor :fallback_raises, default: true
+
+    InvalidValueError = Class.new(StandardError)
+
+    TRUE_OR_FALSE = [true, false].freeze
+
+    def fetch_or_raise(allowed_values, given_value)
+      raise ArgumentError, "allowed_values must be an array; it was #{allowed_values.class}" unless allowed_values.is_a?(Array)
+
+      if allowed_values.include?(given_value)
+        given_value
+      else
+        raise InvalidValueError, <<~MSG
+          fetch_or_raise was called with an invalid value.
+
+          Expected one of: #{allowed_values.inspect}
+          Got: #{given_value.inspect}
+        MSG
+      end
+    end
+
+    def fetch_or_raise_boolean(given_value)
+      fetch_or_raise(TRUE_OR_FALSE, given_value)
+    end
+
+    # TODO: test this
+    def check_incoming_tag(preferred_tag, given_tag)
+      return preferred_tag if given_tag.blank? || preferred_tag == given_tag
+
+      unless silence_warnings?
+        message = <<~MSG
+          Ariadne: note that `#{preferred_tag}` is the preferred tag here;
+          you passed `#{given_tag}` (which will still be used)
+        MSG
+
+        logger.warn(message)
+      end
+
+      given_tag
+    end
+
+    # TODO: test this
+    def check_incoming_attribute(preferred_attribute, given_attribute)
+      return preferred_attribute if given_attribute.blank? || preferred_attribute != given_attribute
+
+      unless silence_warnings?
+        message = <<~MSG
+          Ariadne: note that `#{preferred_attribute}` is the preferred attribute here;
+          you passed `#{given_attribute}` (which will still be used)
+        MSG
+
+        logger.warn(message)
+      end
+
+      given_attribute
+    end
+
+    # TODO: test this
+    def check_incoming_value(preferred_value, given_pair)
+      return preferred_value if given_pair.blank? || !given_pair.is_a?(Hash)
+
+      given_key = given_pair.keys.first
+      given_value = given_pair.values.first
+
+      return preferred_value if given_value.blank?
+
+      unless silence_warnings?
+
+        message = <<~MSG
+          Ariadne: note that `#{preferred_value}` is the preferred value for `#{given_key}` here;
+          you passed `#{given_value}` (which will still be used)
+        MSG
+
+        logger.warn(message)
+      end
+
+      given_value
+    end
+  end
+end