openproject-primer_view_components 0.6.3

data/app/components/primer/alpha/action_bar.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    # Add a general description of component here
+    # Add additional usage considerations or best practices that may aid the user to use the component correctly.
+    class ActionBar < Primer::Component
+      status :alpha
+
+      DEFAULT_SIZE = :medium
+      SIZE_MAPPINGS = {
+        DEFAULT_SIZE => nil,
+        :small => "ActionBar--small",
+        :large => "ActionBar--large"
+      }.freeze
+      SIZE_OPTIONS = SIZE_MAPPINGS.keys.freeze
+
+      renders_many :items, types: {
+        icon_button: lambda { |icon:, label:, **system_arguments|
+          item_id = self.class.generate_id
+
+          with_menu_item(id: item_id, label: label) do |c|
+            c.with_leading_visual_icon(icon: icon)
+          end
+
+          render(Item.new) do
+            render(Primer::Beta::IconButton.new(id: item_id, icon: icon, "aria-label": label, size: @size, scheme: :invisible, **system_arguments))
+          end
+        },
+        divider: lambda {
+          @action_menu.with_divider(hidden: true) if @overflow_menu
+          Divider.new
+        }
+      }
+
+      # @example Default
+      #
+      #   <%= render(Primer::Alpha::ActionBar.new) do |component| %>
+      #     <% component.with_item_icon_button(icon: :search, label: "Search")
+      #     <% component.with_item_icon_button(icon: :pencil, label: "Edit") %>
+      #   <% end %>
+      #
+      # @param size [Symbol] <%= one_of(Primer::Alpha::ActionBar::SIZE_OPTIONS) %>
+      # @param overflow_menu [Boolean] Whether to render the overflow menu.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(size: Primer::Alpha::ActionBar::DEFAULT_SIZE, overflow_menu: true, **system_arguments)
+        @system_arguments = system_arguments
+        @overflow_menu = overflow_menu
+
+        @size = fetch_or_fallback(Primer::Alpha::ActionBar::SIZE_OPTIONS, size, Primer::Alpha::ActionBar::DEFAULT_SIZE)
+
+        @system_arguments[:classes] = class_names(
+          system_arguments[:classes],
+          "ActionBar",
+          SIZE_MAPPINGS[@size]
+        )
+        @system_arguments[:role] = "toolbar"
+
+        return unless overflow_menu
+
+        @action_menu = Primer::Alpha::ActionMenu.new(
+          menu_id: self.class.generate_id,
+          "data-target": "action-bar.moreMenu",
+          hidden: true,
+          classes: "ActionBar-more-menu",
+          anchor_align: :end
+        )
+      end
+
+      private
+
+      def with_menu_item(id:, **system_arguments, &block)
+        return unless @overflow_menu
+
+        system_arguments = {
+          **system_arguments,
+          hidden: true,
+          tag: :button,
+          type: "button",
+          "data-for": id,
+          "data-action": "click:action-bar#menuItemClick"
+        }
+
+        @action_menu.with_item(
+          value: "",
+          **system_arguments,
+          &block
+        )
+      end
+
+      def render?
+        items.any?
+      end
+
+      def render_overflow_menu?
+        @overflow_menu && items.count > 3
+      end
+
+      def before_render
+        @system_arguments[:tag] = render_overflow_menu? ? :"action-bar" : :div
+        @system_arguments[:classes] = class_names(
+          @system_arguments[:classes],
+          "overflow-visible": !render_overflow_menu?
+        )
+        content
+      end
+    end
+  end
+end

data/app/components/primer/alpha/action_bar_element.d.ts

@@ -0,0 +1,16 @@
+declare class ActionBarElement extends HTMLElement {
+    #private;
+    items: HTMLElement[];
+    itemContainer: HTMLElement;
+    moreMenu: HTMLElement;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    menuItemClick(event: Event): void;
+    update(rect?: DOMRect): void;
+}
+declare global {
+    interface Window {
+        ActionBarElement: typeof ActionBarElement;
+    }
+}
+export {};

data/app/components/primer/alpha/action_bar_element.js

@@ -0,0 +1,172 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ActionBarElement_instances, _ActionBarElement_initialBarWidth, _ActionBarElement_previousBarWidth, _ActionBarElement_focusZoneAbortController, _ActionBarElement_itemGap, _ActionBarElement_availableSpace, _ActionBarElement_menuSpace, _ActionBarElement_shrink, _ActionBarElement_grow, _ActionBarElement_showItem, _ActionBarElement_hideItem, _ActionBarElement_menuItems_get;
+import { controller, targets, target } from '@github/catalyst';
+import { focusZone, FocusKeys } from '@primer/behaviors';
+const instersectionObserver = new IntersectionObserver(entries => {
+    for (const entry of entries) {
+        const action = entry.target;
+        if (entry.isIntersecting && action instanceof ActionBarElement) {
+            action.update();
+        }
+    }
+});
+const resizeObserver = new ResizeObserver(entries => {
+    for (const entry of entries) {
+        const action = entry.target;
+        if (action instanceof ActionBarElement) {
+            action.update(entry.contentRect);
+        }
+    }
+});
+let ActionBarElement = class ActionBarElement extends HTMLElement {
+    constructor() {
+        super(...arguments);
+        _ActionBarElement_instances.add(this);
+        _ActionBarElement_initialBarWidth.set(this, void 0);
+        _ActionBarElement_previousBarWidth.set(this, void 0);
+        _ActionBarElement_focusZoneAbortController.set(this, null);
+    }
+    connectedCallback() {
+        var _a, _b, _c, _d;
+        __classPrivateFieldSet(this, _ActionBarElement_previousBarWidth, (_a = this.offsetWidth) !== null && _a !== void 0 ? _a : Infinity, "f");
+        __classPrivateFieldSet(this, _ActionBarElement_initialBarWidth, (_b = this.itemContainer.offsetWidth) !== null && _b !== void 0 ? _b : Infinity, "f");
+        // Calculate the width of all the items before hiding anything
+        for (const item of this.items) {
+            const width = item.getBoundingClientRect().width;
+            const marginLeft = parseInt((_c = window.getComputedStyle(item)) === null || _c === void 0 ? void 0 : _c.marginLeft, 10);
+            const marginRight = parseInt((_d = window.getComputedStyle(item)) === null || _d === void 0 ? void 0 : _d.marginRight, 10);
+            item.setAttribute('data-offset-width', `${width + marginLeft + marginRight}`);
+        }
+        resizeObserver.observe(this);
+        instersectionObserver.observe(this);
+        setTimeout(() => {
+            this.style.overflow = 'visible';
+            this.update();
+        }, 20); // Wait for the items to be rendered, making this really short to avoid a flash of unstyled content
+    }
+    disconnectedCallback() {
+        resizeObserver.unobserve(this);
+        instersectionObserver.unobserve(this);
+    }
+    menuItemClick(event) {
+        var _a;
+        const currentTarget = event.currentTarget;
+        const id = currentTarget === null || currentTarget === void 0 ? void 0 : currentTarget.getAttribute('data-for');
+        if (id) {
+            (_a = document.getElementById(id)) === null || _a === void 0 ? void 0 : _a.click();
+        }
+    }
+    update(rect = this.getBoundingClientRect()) {
+        // Only recalculate if the bar width changed
+        if (rect.width <= __classPrivateFieldGet(this, _ActionBarElement_previousBarWidth, "f") || __classPrivateFieldGet(this, _ActionBarElement_previousBarWidth, "f") === 0) {
+            __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_shrink).call(this);
+        }
+        else if (rect.width > __classPrivateFieldGet(this, _ActionBarElement_previousBarWidth, "f")) {
+            __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_grow).call(this);
+        }
+        __classPrivateFieldSet(this, _ActionBarElement_previousBarWidth, rect.width, "f");
+        if (rect.width <= __classPrivateFieldGet(this, _ActionBarElement_initialBarWidth, "f")) {
+            this.style.justifyContent = 'space-between';
+        }
+        else {
+            this.style.justifyContent = 'flex-end';
+        }
+        if (__classPrivateFieldGet(this, _ActionBarElement_focusZoneAbortController, "f")) {
+            __classPrivateFieldGet(this, _ActionBarElement_focusZoneAbortController, "f").abort();
+        }
+        __classPrivateFieldSet(this, _ActionBarElement_focusZoneAbortController, focusZone(this.itemContainer, {
+            bindKeys: FocusKeys.ArrowHorizontal | FocusKeys.HomeAndEnd,
+            focusOutBehavior: 'wrap',
+            focusableElementFilter: element => {
+                return !element.closest('.ActionBar-item[hidden]');
+            }
+        }), "f");
+    }
+};
+_ActionBarElement_initialBarWidth = new WeakMap(), _ActionBarElement_previousBarWidth = new WeakMap(), _ActionBarElement_focusZoneAbortController = new WeakMap(), _ActionBarElement_instances = new WeakSet(), _ActionBarElement_itemGap = function _ActionBarElement_itemGap() {
+    var _a;
+    return parseInt((_a = window.getComputedStyle(this.itemContainer)) === null || _a === void 0 ? void 0 : _a.columnGap, 10) || 0;
+}, _ActionBarElement_availableSpace = function _ActionBarElement_availableSpace() {
+    // Get the offset of the item container from the container edge
+    return this.offsetWidth - this.itemContainer.offsetWidth;
+}, _ActionBarElement_menuSpace = function _ActionBarElement_menuSpace() {
+    if (this.moreMenu.hidden) {
+        return 0;
+    }
+    return this.moreMenu.offsetWidth + __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_itemGap).call(this);
+}, _ActionBarElement_shrink = function _ActionBarElement_shrink() {
+    if (this.items[0].hidden) {
+        return;
+    }
+    let index = this.items.length - 1;
+    for (const item of this.items.reverse()) {
+        if (!item.hidden && __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_availableSpace).call(this) < __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_menuSpace).call(this)) {
+            __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_hideItem).call(this, index);
+        }
+        else if (__classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_availableSpace).call(this) >= __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_menuSpace).call(this)) {
+            return;
+        }
+        index--;
+    }
+}, _ActionBarElement_grow = function _ActionBarElement_grow() {
+    // If last item is visible, there is no need to grow
+    if (!this.items[this.items.length - 1].hidden) {
+        return;
+    }
+    let index = 0;
+    for (const item of this.items) {
+        if (item.hidden) {
+            const offsetWidth = Number(item.getAttribute('data-offset-width'));
+            if (__classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_availableSpace).call(this) >= __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_menuSpace).call(this) + offsetWidth || index === this.items.length - 1) {
+                __classPrivateFieldGet(this, _ActionBarElement_instances, "m", _ActionBarElement_showItem).call(this, index);
+            }
+            else {
+                return;
+            }
+        }
+        index++;
+    }
+    if (!this.items[this.items.length - 1].hidden) {
+        this.moreMenu.hidden = true;
+    }
+}, _ActionBarElement_showItem = function _ActionBarElement_showItem(index) {
+    this.items[index].hidden = false;
+    __classPrivateFieldGet(this, _ActionBarElement_instances, "a", _ActionBarElement_menuItems_get)[index].hidden = true;
+}, _ActionBarElement_hideItem = function _ActionBarElement_hideItem(index) {
+    this.items[index].hidden = true;
+    __classPrivateFieldGet(this, _ActionBarElement_instances, "a", _ActionBarElement_menuItems_get)[index].hidden = false;
+    if (this.moreMenu.hidden) {
+        this.moreMenu.hidden = false;
+    }
+}, _ActionBarElement_menuItems_get = function _ActionBarElement_menuItems_get() {
+    return this.moreMenu.querySelectorAll('[role="menu"] > li');
+};
+__decorate([
+    targets
+], ActionBarElement.prototype, "items", void 0);
+__decorate([
+    target
+], ActionBarElement.prototype, "itemContainer", void 0);
+__decorate([
+    target
+], ActionBarElement.prototype, "moreMenu", void 0);
+ActionBarElement = __decorate([
+    controller
+], ActionBarElement);
+window.ActionBarElement = ActionBarElement;

data/app/components/primer/alpha/action_bar_element.ts

@@ -0,0 +1,175 @@
+import {controller, targets, target} from '@github/catalyst'
+import {focusZone, FocusKeys} from '@primer/behaviors'
+
+const instersectionObserver = new IntersectionObserver(entries => {
+  for (const entry of entries) {
+    const action = entry.target
+    if (entry.isIntersecting && action instanceof ActionBarElement) {
+      action.update()
+    }
+  }
+})
+
+const resizeObserver = new ResizeObserver(entries => {
+  for (const entry of entries) {
+    const action = entry.target
+    if (action instanceof ActionBarElement) {
+      action.update(entry.contentRect)
+    }
+  }
+})
+
+@controller
+class ActionBarElement extends HTMLElement {
+  @targets items: HTMLElement[]
+  @target itemContainer: HTMLElement
+  @target moreMenu: HTMLElement
+
+  #initialBarWidth: number
+  #previousBarWidth: number
+  #focusZoneAbortController: AbortController | null = null
+
+  connectedCallback() {
+    this.#previousBarWidth = this.offsetWidth ?? Infinity
+    this.#initialBarWidth = this.itemContainer.offsetWidth ?? Infinity
+
+    // Calculate the width of all the items before hiding anything
+    for (const item of this.items) {
+      const width = item.getBoundingClientRect().width
+      const marginLeft = parseInt(window.getComputedStyle(item)?.marginLeft, 10)
+      const marginRight = parseInt(window.getComputedStyle(item)?.marginRight, 10)
+      item.setAttribute('data-offset-width', `${width + marginLeft + marginRight}`)
+    }
+
+    resizeObserver.observe(this)
+    instersectionObserver.observe(this)
+
+    setTimeout(() => {
+      this.style.overflow = 'visible'
+      this.update()
+    }, 20) // Wait for the items to be rendered, making this really short to avoid a flash of unstyled content
+  }
+
+  disconnectedCallback() {
+    resizeObserver.unobserve(this)
+    instersectionObserver.unobserve(this)
+  }
+
+  menuItemClick(event: Event) {
+    const currentTarget = event.currentTarget as HTMLButtonElement
+
+    const id = currentTarget?.getAttribute('data-for')
+
+    if (id) {
+      document.getElementById(id)?.click()
+    }
+  }
+
+  update(rect: DOMRect = this.getBoundingClientRect()) {
+    // Only recalculate if the bar width changed
+    if (rect.width <= this.#previousBarWidth || this.#previousBarWidth === 0) {
+      this.#shrink()
+    } else if (rect.width > this.#previousBarWidth) {
+      this.#grow()
+    }
+    this.#previousBarWidth = rect.width
+
+    if (rect.width <= this.#initialBarWidth) {
+      this.style.justifyContent = 'space-between'
+    } else {
+      this.style.justifyContent = 'flex-end'
+    }
+    if (this.#focusZoneAbortController) {
+      this.#focusZoneAbortController.abort()
+    }
+    this.#focusZoneAbortController = focusZone(this.itemContainer, {
+      bindKeys: FocusKeys.ArrowHorizontal | FocusKeys.HomeAndEnd,
+      focusOutBehavior: 'wrap',
+      focusableElementFilter: element => {
+        return !element.closest('.ActionBar-item[hidden]')
+      }
+    })
+  }
+
+  #itemGap(): number {
+    return parseInt(window.getComputedStyle(this.itemContainer)?.columnGap, 10) || 0
+  }
+
+  #availableSpace(): number {
+    // Get the offset of the item container from the container edge
+    return this.offsetWidth - this.itemContainer.offsetWidth
+  }
+
+  #menuSpace(): number {
+    if (this.moreMenu.hidden) {
+      return 0
+    }
+    return this.moreMenu.offsetWidth + this.#itemGap()
+  }
+
+  #shrink() {
+    if (this.items[0]!.hidden) {
+      return
+    }
+
+    let index = this.items.length - 1
+    for (const item of this.items.reverse()) {
+      if (!item.hidden && this.#availableSpace() < this.#menuSpace()) {
+        this.#hideItem(index)
+      } else if (this.#availableSpace() >= this.#menuSpace()) {
+        return
+      }
+      index--
+    }
+  }
+
+  #grow() {
+    // If last item is visible, there is no need to grow
+    if (!this.items[this.items.length - 1]!.hidden) {
+      return
+    }
+    let index = 0
+    for (const item of this.items) {
+      if (item.hidden) {
+        const offsetWidth = Number(item.getAttribute('data-offset-width'))
+
+        if (this.#availableSpace() >= this.#menuSpace() + offsetWidth || index === this.items.length - 1) {
+          this.#showItem(index)
+        } else {
+          return
+        }
+      }
+      index++
+    }
+
+    if (!this.items[this.items.length - 1]!.hidden) {
+      this.moreMenu.hidden = true
+    }
+  }
+
+  #showItem(index: number) {
+    this.items[index]!.hidden = false
+    this.#menuItems[index]!.hidden = true
+  }
+
+  #hideItem(index: number) {
+    this.items[index]!.hidden = true
+    this.#menuItems[index]!.hidden = false
+
+    if (this.moreMenu.hidden) {
+      this.moreMenu.hidden = false
+    }
+  }
+
+  get #menuItems(): NodeListOf<HTMLElement> {
+    return this.moreMenu.querySelectorAll('[role="menu"] > li')
+  }
+}
+
+declare global {
+  interface Window {
+    ActionBarElement: typeof ActionBarElement
+  }
+}
+
+window.ActionBarElement = ActionBarElement

data/app/components/primer/alpha/action_list/divider.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class ActionList
+      # Separator with optional text rendered above groups or between individual items.
+      class Divider < Primer::Component
+        DEFAULT_SCHEME = :subtle
+        SCHEME_MAPPINGS = {
+          DEFAULT_SCHEME => nil,
+          :filled => "ActionList-sectionDivider--filled"
+        }.freeze
+        SCHEME_OPTIONS = SCHEME_MAPPINGS.keys.freeze
+
+        # @param scheme [Symbol] Display a background color if scheme is `filled`.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(scheme: DEFAULT_SCHEME, **system_arguments)
+          @system_arguments = system_arguments
+          @system_arguments[:tag] = :li
+          @system_arguments[:role] = :presentation
+          @system_arguments[:'aria-hidden'] = true
+          @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
+          @system_arguments[:classes] = class_names(
+            "ActionList-sectionDivider",
+            SCHEME_MAPPINGS[@scheme]
+          )
+        end
+
+        def call
+          render(Primer::BaseComponent.new(**@system_arguments)) { content }
+        end
+      end
+    end
+  end
+end

data/app/components/primer/alpha/action_list/form_wrapper.html.erb

@@ -0,0 +1,10 @@
+<% if form_required? %>
+  <%= form_with(url: @action, method: @http_method, **@form_arguments) do %>
+    <% if render_input? %>
+      <%= render(Primer::BaseComponent.new(tag: :input, **@input_arguments)) %>
+    <% end %>
+    <%= content %>
+  <% end %>
+<% else %>
+  <%= content %>
+<% end %>

data/app/components/primer/alpha/action_list/form_wrapper.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class ActionList
+      # Utility component for wrapping ActionLists or individual ActionList::Items in forms.
+      class FormWrapper < Primer::Component
+        DEFAULT_HTTP_METHOD = :get
+        HTTP_METHOD_OPTIONS = [
+          DEFAULT_HTTP_METHOD,
+          :post,
+          :patch,
+          :put,
+          :delete,
+          :head
+        ].freeze
+
+        def initialize(list:, action: nil, **form_arguments)
+          @list = list
+          @form_arguments = form_arguments
+
+          @action = action
+          @http_method = extract_http_method(@form_arguments)
+
+          name = @form_arguments.delete(:name)
+          value = @form_arguments.delete(:value) || name
+
+          @input_arguments = {
+            type: :hidden,
+            name: name,
+            value: value,
+            data: { list_item_input: true },
+            **(@form_arguments.delete(:input_arguments) || {})
+          }
+        end
+
+        def get?
+          @http_method == :get
+        end
+
+        def form_required?
+          @action && !get?
+        end
+
+        def render_input?
+          @input_arguments[:name].present?
+        end
+
+        private
+
+        def extract_http_method(args)
+          if (http_method = args.delete(:method))
+            HTTP_METHOD_OPTIONS.include?(http_method) ? http_method : DEFAULT_HTTP_METHOD
+          else
+            DEFAULT_HTTP_METHOD
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/primer/alpha/action_list/heading.html.erb

@@ -0,0 +1,8 @@
+<%= render(Primer::BaseComponent.new(tag: :div, **@system_arguments)) do %>
+  <%= render(Primer::BaseComponent.new(tag: @tag, classes: "ActionList-sectionDivider-title", id: title_id)) do %>
+    <%= @title %>
+  <% end %>
+  <%= render Primer::ConditionalWrapper.new(condition: subtitle?, tag: :span, classes: "ActionListItem-description", id: subtitle_id) do %>
+    <%= @subtitle %>
+  <% end %>
+<% end %>

data/app/components/primer/alpha/action_list/heading.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class ActionList
+      # Heading used to describe each sub list within an action list.
+      class Heading < Primer::Component
+        DEFAULT_SCHEME = :subtle
+        SCHEME_MAPPINGS = {
+          DEFAULT_SCHEME => nil,
+          :filled => "ActionList-sectionDivider--filled"
+        }.freeze
+        SCHEME_OPTIONS = SCHEME_MAPPINGS.keys.freeze
+        HEADING_MIN = 1
+        HEADING_MAX = 6
+        HEADING_LEVELS = (HEADING_MIN..HEADING_MAX).to_a.freeze
+
+        attr_reader :title_id, :subtitle_id
+
+        # @param title [String] Sub list title.
+        # @param heading_level [Integer] Heading level. Level 2 results in an `<h2>` tag, level 3 an `<h3>` tag, etc.
+        # @param subtitle [String] Optional sub list description.
+        # @param scheme [Symbol] Display a background color if scheme is `filled`.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(title:, heading_level: 3, scheme: DEFAULT_SCHEME, subtitle: nil, **system_arguments)
+          raise "Heading level must be between #{HEADING_MIN} and #{HEADING_MAX}" unless HEADING_LEVELS.include?(heading_level)
+
+          @heading_level = heading_level
+          @tag = :"h#{heading_level}"
+          @system_arguments = deny_tag_argument(**system_arguments)
+          @title = title
+          @subtitle = subtitle
+          @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
+          @system_arguments[:classes] = class_names(
+            "ActionList-sectionDivider",
+            SCHEME_MAPPINGS[@scheme],
+            @system_arguments[:classes]
+          )
+
+          @title_id = self.class.generate_id(base_name: "heading-title")
+          @subtitle_id = self.class.generate_id(base_name: "heading-subtitle")
+        end
+
+        def subtitle?
+          @subtitle.present?
+        end
+      end
+    end
+  end
+end