@openproject/primer-view-components

[ { "fully_qualified_name": "Primer::Alpha::ActionBar", "description": "Add a general description of component here\nAdd additional usage considerations or best practices that may aid the user to use the component correctly.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": false, "component": "ActionBar", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionBar", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_bar.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_bar/default/", "parameters": [ { "name": "size", "type": "Symbol", "default": "`:medium`", "description": "One of `:large`, `:medium`, or `:small`." }, { "name": "overflow_menu", "type": "Boolean", "default": "`true`", "description": "Whether to render the overflow menu." }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "{{link_to_system_arguments_docs}}" } ], "slots": [ { "name": "items", "description": null, "parameters": [] } ], "methods": [], "previews": [ { "preview_path": "primer/alpha/action_bar/default", "name": "default", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_bar/inline", "name": "inline", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_bar/playground", "name": "playground", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_bar/small", "name": "small", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_bar/medium", "name": "medium", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_bar/large", "name": "large", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } } ], "subcomponents": [ { "fully_qualified_name": "Primer::Alpha::ActionBar::Item", "description": "ActionBar::Item is an internal component that wraps the items in a div with the `ActionBar-item` class.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": false, "component": "ActionBar::Item", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionBarItem", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_bar/item.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_bar/item/default/", "parameters": [ { "name": "item_content", "type": "String", "default": "N/A", "description": "The content to render inside the item." }, { "name": "item_arguments", "type": "Hash", "default": "N/A", "description": "{{link_to_system_arguments_docs}}" } ], "slots": [], "methods": [], "previews": [], "subcomponents": [] }, { "fully_qualified_name": "Primer::Alpha::ActionBar::Divider", "description": "ActionBar::Item is an internal component that wraps the items in a div with the `ActionBar-item` class.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": false, "component": "ActionBar::Divider", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionBarDivider", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_bar/divider.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_bar/divider/default/", "parameters": [], "slots": [], "methods": [], "previews": [], "subcomponents": [] } ] }, { "fully_qualified_name": "Primer::Alpha::ActionList", "description": "An ActionList is a styled list of links. It acts as the base component for many\nother menu-type components, including `ActionMenu` and `SelectPanel`, as well as\nthe navigational component `NavList`.\n\nEach item in an action list can be augmented by specifying corresponding leading\nand/or trailing visuals.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": true, "component": "ActionList", "status": "alpha", "a11y_reviewed": true, "short_name": "ActionList", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_list.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_list/default/", "parameters": [ { "name": "id", "type": "String", "default": "`self.class.generate_id`", "description": "HTML ID value." }, { "name": "role", "type": "Boolean", "default": "`nil`", "description": "ARIA role describing the function of the list. listbox and menu are a common values." }, { "name": "item_classes", "type": "String", "default": "`nil`", "description": "Additional CSS classes to attach to items." }, { "name": "scheme", "type": "Symbol", "default": "`:full`", "description": "One of `:full` or `:inset`. `inset` children are offset (vertically and horizontally) from list edges. `full` (default) children are flush (vertically and horizontally) with list edges." }, { "name": "show_dividers", "type": "Boolean", "default": "`false`", "description": "Display a divider above each item in the list when it does not follow a header or divider." }, { "name": "select_variant", "type": "Symbol", "default": "`:none`", "description": "How items may be selected in the list. One of `:multiple`, `:multiple_checkbox`, `:none`, or `:single`." }, { "name": "aria_selection_variant", "type": "Symbol", "default": "`:checked`", "description": "Specifies which aria selection to use. One of `:checked` or `:selected`." }, { "name": "form_arguments", "type": "Hash", "default": "`{}`", "description": "Allows an `ActionList` to act as a select list in multi- and single-select modes. Pass the `builder:` and `name:` options to this hash. `builder:` should be an instance of `ActionView::Helpers::FormBuilder`, which are created by the standard Rails `#form_with` and `#form_for` helpers. The `name:` option is the desired name of the field that will be included in the params sent to the server on form submission. *NOTE*: Consider using an {{#link_to_component}}Primer::Alpha::ActionMenu{{/link_to_component}} instead of using this feature directly." }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "{{link_to_system_arguments_docs}}" } ], "slots": [ { "name": "heading", "description": "Heading text rendered above the list of items.", "parameters": [ { "name": "component_klass", "type": "Class", "default": "N/A", "description": "The class to use instead of the default {{#link_to_component}}Primer::Alpha::ActionList::Heading{{/link_to_component}}." }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "The arguments accepted by `component_klass`." } ] }, { "name": "items", "description": "Items. Items can be individual items, avatar items, or dividers. See the documentation for `#with_item`, `#with_divider`, and `#with_avatar_item` respectively for more information.", "parameters": [] } ], "methods": [ { "name": "with_item", "description": "Adds an item to the list.", "parameters": [ { "name": "component_klass", "type": "Class", "default": "N/A", "description": "The class to use instead of the default {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}" }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "These arguments are forwarded to {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}, or whatever class is passed as the `component_klass` argument." } ], "return_types": [] }, { "name": "with_divider", "description": "Adds a divider to the list. Dividers visually separate items.", "parameters": [ { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "The arguments accepted by {{#link_to_component}}Primer::Alpha::ActionList::Divider{{/link_to_component}}." } ], "return_types": [] }, { "name": "with_avatar_item", "description": "Adds an avatar item to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image.", "parameters": [ { "name": "src", "type": "String", "default": "N/A", "description": "The source url of the avatar image." }, { "name": "username", "type": "String", "default": "N/A", "description": "The username associated with the avatar." }, { "name": "full_name", "type": "String", "default": "`nil`", "description": "Optional. The user's full name." }, { "name": "full_name_scheme", "type": "Symbol", "default": "`:block`", "description": "Optional. How to display the user's full name. One of `:block` or `:inline`." }, { "name": "component_klass", "type": "Class", "default": "`ActionList::Item`", "description": "The class to use instead of the default {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}" }, { "name": "avatar_arguments", "type": "Hash", "default": "`{}`", "description": "Optional. The arguments accepted by {{#link_to_component}}Primer::Beta::Avatar{{/link_to_component}}" }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "These arguments are forwarded to {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}, or whatever class is passed as the `component_klass` argument." } ], "return_types": [] }, { "name": "id", "description": "Returns the value of attribute id.", "parameters": [], "return_types": [] }, { "name": "select_variant", "description": "Returns the value of attribute select_variant.", "parameters": [], "return_types": [] }, { "name": "role", "description": "Returns the value of attribute role.", "parameters": [], "return_types": [] }, { "name": "aria_selection_variant", "description": "Returns the value of attribute aria_selection_variant.", "parameters": [], "return_types": [] }, { "name": "build_item", "description": "Builds a new item but does not add it to the list. Use this method\ninstead of the `#with_item` slot if you need to render an item outside\nthe context of a list, eg. if rendering additional items to append to\nan existing list, perhaps via a separate HTTP request.", "parameters": [ { "name": "component_klass", "type": "Class", "default": "`ActionList::Item`", "description": "The class to use instead of the default {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}" }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "These arguments are forwarded to {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}, or whatever class is passed as the `component_klass` argument." } ], "return_types": [] }, { "name": "build_avatar_item", "description": "Builds a new avatar item but does not add it to the list. Avatar items\nare a convenient way to accessibly add an item with a leading avatar\nimage. Use this method instead of the `#with_avatar_item` slot if you\nneed to render an avatar item outside the context of a list, eg. if\nrendering additional items to append to an existing list, perhaps via\na separate HTTP request.", "parameters": [ { "name": "src", "type": "String", "default": "N/A", "description": "The source url of the avatar image." }, { "name": "username", "type": "String", "default": "N/A", "description": "The username associated with the avatar." }, { "name": "full_name", "type": "String", "default": "`nil`", "description": "Optional. The user's full name." }, { "name": "full_name_scheme", "type": "Symbol", "default": "`:block`", "description": "Optional. How to display the user's full name. One of `:block` or `:inline`." }, { "name": "component_klass", "type": "Class", "default": "`ActionList::Item`", "description": "The class to use instead of the default {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}" }, { "name": "avatar_arguments", "type": "Hash", "default": "`{}`", "description": "Optional. The arguments accepted by {{#link_to_component}}Primer::Beta::Avatar{{/link_to_component}}" }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "These arguments are forwarded to {{#link_to_component}}Primer::Alpha::ActionList::Item{{/link_to_component}}, or whatever class is passed as the `component_klass` argument." } ], "return_types": [] }, { "name": "post_list_content_block", "description": "Returns the value of attribute post_list_content_block.", "parameters": [], "return_types": [] } ], "previews": [ { "preview_path": "primer/alpha/action_list/playground", "name": "playground", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/default", "name": "default", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/leading_visuals", "name": "leading_visuals", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/with_manual_dividers", "name": "with_manual_dividers", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/divider", "name": "divider", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/heading", "name": "heading", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item", "name": "item", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/avatar_item", "name": "avatar_item", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_default", "name": "item_default", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_size_large", "name": "item_size_large", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_size_xlarge", "name": "item_size_xlarge", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_leading_visual", "name": "item_leading_visual", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_trailing_visual", "name": "item_trailing_visual", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_leading_trailing_visual", "name": "item_leading_trailing_visual", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_with_description", "name": "item_with_description", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_with_description_inline", "name": "item_with_description_inline", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_trailing_action", "name": "item_trailing_action", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_danger", "name": "item_danger", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_disabled", "name": "item_disabled", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_wrap_label", "name": "item_wrap_label", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_truncate_label", "name": "item_truncate_label", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/item_active", "name": "item_active", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/long_label_with_tooltip", "name": "long_label_with_tooltip", "snapshot": "true", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/long_label_wrap", "name": "long_label_wrap", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/long_label_truncate_no_tooltip", "name": "long_label_truncate_no_tooltip", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/long_label_show_tooltip_with_truncate_label", "name": "long_label_show_tooltip_with_truncate_label", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } }, { "preview_path": "primer/alpha/action_list/listbox", "name": "listbox", "snapshot": "false", "skip_rules": { "wont_fix": [ "region" ], "will_fix": [ "color-contrast" ] } } ], "subcomponents": [ { "fully_qualified_name": "Primer::Alpha::ActionList::Item", "description": "An individual `ActionList` item. Items can optionally include leading and/or trailing visuals,\nsuch as icons, avatars, and counters.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": false, "component": "ActionList::Item", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionListItem", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_list/item.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_list/item/default/", "parameters": [ { "name": "list", "type": "Primer::Alpha::ActionList", "default": "N/A", "description": "The list that contains this item. Used internally." }, { "name": "parent", "type": "Primer::Alpha::ActionList::Item", "default": "`nil`", "description": "This item's parent item. `nil` if this item is at the root. Used internally." }, { "name": "label", "type": "String", "default": "`nil`", "description": "Item label. If no label is provided, content is used." }, { "name": "item_id", "type": "String", "default": "`nil`", "description": "An ID that will be attached to the item's `<li>` element as `data-item-id` for distinguishing between items, perhaps in JavaScript." }, { "name": "label_classes", "type": "String", "default": "`nil`", "description": "CSS classes that will be added to the label." }, { "name": "label_arguments", "type": "Hash", "default": "`{}`", "description": "{{link_to_system_arguments_docs}} used to construct the label." }, { "name": "content_arguments", "type": "Hash", "default": "`{}`", "description": "{{link_to_system_arguments_docs}} used to construct the item's anchor or button tag." }, { "name": "form_arguments", "type": "Hash", "default": "`{}`", "description": "Allows the item to submit a form on click. The URL passed in the `href:` option will be used as the form action. Pass the `method:` option to this hash to control what kind of request is made, One of `:delete`, `:get`, `:head`, `:patch`, `:post`, or `:put`. The `name:` option is required and specifies the desired name of the field that will be included in the params sent to the server on form submission. Specify the `value:` option to send a custom value to the server; otherwise the value of `name:` is sent." }, { "name": "truncate_label", "type": "Boolean | Symbol", "default": "`:none`", "description": "How the label should be truncated when the text does not fit inside the bounds of the list item. One of `false`, `:none`, `:show_tooltip`, `:truncate`, or `true`. Pass `false` or `:none` to wrap label text. Pass `true` or `:truncate` to truncate labels with ellipses. Pass `:show_tooltip` to show the entire label contents in a tooltip when the item is hovered." }, { "name": "href", "type": "String", "default": "`nil`", "description": "Link URL." }, { "name": "role", "type": "String", "default": "`nil`", "description": "ARIA role describing the function of the item." }, { "name": "size", "type": "Symbol", "default": "`:medium`", "description": "Controls block sizing of the item." }, { "name": "scheme", "type": "Symbol", "default": "`:default`", "description": "Controls color/style based on behavior." }, { "name": "disabled", "type": "Boolean", "default": "`false`", "description": "Disabled items are not clickable and visually dim." }, { "name": "description_scheme", "type": "Symbol", "default": "`:block`", "description": "Display description inline with label, or block on the next line. One of `:block` or `:inline`." }, { "name": "active", "type": "Boolean", "default": "`false`", "description": "If the parent list's `select_variant` is set to `:single` or `:multiple`, causes this item to render checked." }, { "name": "on_click", "type": "String", "default": "`nil`", "description": "JavaScript to execute when the item is clicked." }, { "name": "id", "type": "String", "default": "`self.class.generate_id`", "description": "Used internally." }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "{{link_to_system_arguments_docs}}" } ], "slots": [ { "name": "description", "description": "Description content that complements the item's label, with optional test_selector.\nSee `ActionList`'s `description_scheme` argument for layout options.", "parameters": [ { "name": "legacy_content", "type": "String", "default": "N/A", "description": "Slot content, provided for backwards-compatibility. Pass a content block instead, or call `with_content`, eg. `component.with_description { \"My description\" }` or `component.with_description.with_content(\"My description\")`." }, { "name": "test_selector", "type": "String", "default": "N/A", "description": "The value of this argument is set as the value of a `data-test-selector` HTML attribute on the description element." } ] }, { "name": "leading_visual", "description": "An icon, avatar, SVG, or custom content that will render to the left of the label.\n\nTo render an icon, call the `with_leading_visual_icon` method, which accepts the arguments accepted by {{#link_to_component}}Primer::Beta::Octicon{{/link_to_component}}.\n\nTo render an SVG, call the `with_leading_visual_svg` method.\n\nTo render custom content, call the `with_leading_visual_content` method and pass a block that returns a string.", "parameters": [] }, { "name": "trailing_visual", "description": "An icon, label, counter, or text to render to the right of the label.\n\nTo render an icon, call the `with_leading_visual_icon` method, which accepts the arguments accepted by {{#link_to_component}}Primer::Beta::Octicon{{/link_to_component}}.\n\nTo render a label, call the `with_leading_visual_label` method, which accepts the arguments accepted by {{#link_to_component}}Primer::Beta::Label{{/link_to_component}}.\n\nTo render a counter, call the `with_leading_visual_counter` method, which accepts the arguments accepted by {{#link_to_component}}Primer::Beta::Counter{{/link_to_component}}.\n\nTo render text, call the `with_leading_visual_text` method and pass a block that returns a string. Eg:\n```ruby\nwith_leading_visual_text { \"Text here\" }\n```", "parameters": [] }, { "name": "trailing_action", "description": "A button rendered after the trailing icon that can be used to show a menu, activate\na dialog, etc.", "parameters": [ { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "The arguments accepted by {{#link_to_component}}Primer::Beta::IconButton{{/link_to_component}}." } ] }, { "name": "tooltip", "description": "`Tooltip` that appears on mouse hover or keyboard focus over the trailing action button. Use tooltips sparingly and as\na last resort. **Important:** This tooltip defaults to `type: :description`. In a few scenarios, `type: :label` may be\nmore appropriate. Consult the {{#link_to_component}}Primer::Alpha::Tooltip{{/link_to_component}} documentation for more information.", "parameters": [ { "name": "type", "type": "Symbol", "default": "`:description`", "description": "One of `:description` or `:label`." }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "The arguments accepted by {{#link_to_component}}Primer::Alpha::Tooltip{{/link_to_component}}." } ] } ], "methods": [ { "name": "id", "description": "Returns the value of attribute id.", "parameters": [], "return_types": [] }, { "name": "item_id", "description": "Returns the value of attribute item_id.", "parameters": [], "return_types": [] }, { "name": "list", "description": "Returns the value of attribute list.", "parameters": [], "return_types": [] }, { "name": "href", "description": "Returns the value of attribute href.", "parameters": [], "return_types": [] }, { "name": "active", "description": "Returns the value of attribute active.", "parameters": [], "return_types": [] }, { "name": "disabled", "description": "Returns the value of attribute disabled.", "parameters": [], "return_types": [] }, { "name": "parent", "description": "Returns the value of attribute parent.", "parameters": [], "return_types": [] }, { "name": "active?", "description": "Returns the value of attribute active.\nWhether or not this item is active.", "parameters": [], "return_types": [ "Boolean" ] }, { "name": "disabled?", "description": "Returns the value of attribute disabled.\nWhether or not this item is disabled.", "parameters": [], "return_types": [ "Boolean" ] } ], "previews": [], "subcomponents": [] }, { "fully_qualified_name": "Primer::Alpha::ActionList::Heading", "description": "Heading used to describe each sub list within an action list.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": false, "component": "ActionList::Heading", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionListHeading", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_list/heading.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_list/heading/default/", "parameters": [ { "name": "title", "type": "String", "default": "N/A", "description": "Sub list title." }, { "name": "heading_level", "type": "Integer", "default": "`3`", "description": "Heading level. Level 2 results in an `<h2>` tag, level 3 an `<h3>` tag, etc." }, { "name": "subtitle", "type": "String", "default": "`nil`", "description": "Optional sub list description." }, { "name": "scheme", "type": "Symbol", "default": "`:subtle`", "description": "Display a background color if scheme is `filled`." }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "{{link_to_system_arguments_docs}}" } ], "slots": [], "methods": [ { "name": "title_id", "description": "Returns the value of attribute title_id.", "parameters": [], "return_types": [] }, { "name": "subtitle_id", "description": "Returns the value of attribute subtitle_id.", "parameters": [], "return_types": [] } ], "previews": [], "subcomponents": [] }, { "fully_qualified_name": "Primer::Alpha::ActionList::FormWrapper", "description": "Utility component for wrapping ActionLists or individual ActionList::Items in forms.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": false, "component": "ActionList::FormWrapper", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionListFormWrapper", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_list/form_wrapper.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_list/form_wrapper/default/", "parameters": [], "slots": [], "methods": [], "previews": [], "subcomponents": [] }, { "fully_qualified_name": "Primer::Alpha::ActionList::Divider", "description": "Separator with optional text rendered above groups or between individual items.", "accessibility_docs": null, "is_form_component": false, "is_published": true, "requires_js": false, "component": "ActionList::Divider", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionListDivider", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_list/divider.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_list/divider/default/", "parameters": [ { "name": "scheme", "type": "Symbol", "default": "`:subtle`", "description": "Display a background color if scheme is `filled`." }, { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "{{link_to_system_arguments_docs}}" } ], "slots": [], "methods": [], "previews": [], "subcomponents": [] } ] }, { "fully_qualified_name": "Primer::Alpha::ActionMenu", "description": "ActionMenu is used for actions, navigation, to display secondary options, or single/multi select lists. They appear when\nusers interact with buttons, actions, or other controls.\n\nThe only allowed elements for the `Item` components are: `:a`, `:button`, and `:clipboard-copy`. The default is `:button`.\n\n### Select variants\n\nWhile `ActionMenu`s default to a list of buttons that can link to other pages, copy text to the clipboard, etc, they also support\n`single` and `multiple` select variants. The single select variant allows a single item to be \"selected\" (i.e. marked \"active\")\nwhen clicked, which will cause a check mark to appear to the left of the item text. When the `multiple` select variant is chosen,\nmultiple items may be selected and check marks will appear next to each selected item.\n\nUse the `select_variant:` option to control which variant the `ActionMenu` uses. For more information, see the documentation on\nsupported arguments below.\n\n### Dynamic labels\n\nWhen using the `single` select variant, an optional label indicating the selected item can be displayed inside the menu button.\nDynamic labels can also be prefixed with custom text.\n\nPass `dynamic_label: true` to enable dynamic label behavior, and pass `dynamic_label_prefix: \"<string>\"` to set a custom prefix.\nFor more information, see the documentation on supported arguments below.\n\n### `ActionMenu`s as form inputs\n\nWhen using either the `single` or `multiple` select variants, `ActionMenu`s can be used as form inputs. They behave very\nsimilarly to how HTML `<select>` boxes behave, and play nicely with Rails' built-in form mechanisms. Pass arguments via the\n`form_arguments:` argument, including the Rails form builder object and the name of the field:\n\n```erb\n<% form_with(url: update_merge_strategy_path) do |f| %>\n <%= render(Primer::Alpha::ActionMenu.new(form_arguments: { builder: f, name: \"merge_strategy\" })) do |menu| %>\n <% menu.with_item(label: \"Fast forward\", data: { value: \"fast_forward\" }) %>\n <% menu.with_item(label: \"Recursive\", data: { value: \"recursive\" }) %>\n <% menu.with_item(label: \"Ours\", data: { value: \"ours\" }) %>\n <% menu.with_item(label: \"Theirs\", data: { value: \"theirs\" }) %>\n <% end %>\n<% end %>\n```\n\nThe value of the `data: { value: ... }` argument is sent to the server on submit, keyed using the name provided above\n(eg. `\"merge_strategy\"`). If no value is provided for an item, the value of that item is the item's label. Here's the\ncorresponding `MergeStrategyController` that might be written to handle the form above:\n\n```ruby\nclass MergeStrategyController < ApplicationController\n def update\n puts \"You chose #{merge_strategy_params[:merge_strategy]}\"\n end\n\n private\n\n def merge_strategy_params\n params.permit(:merge_strategy)\n end\nend\n```\n\n### `ActionMenu` items that submit forms\n\nWhereas `ActionMenu` items normally permit navigation via `<a>` tags which make HTTP `get` requests, `ActionMenu` items\nalso permit navigation via `POST` requests. To enable this behavior, include the `href:` argument as normal, but also pass\nthe `form_arguments:` argument to the appropriate item:\n\n```erb\n<%= render(Primer::Alpha::ActionMenu.new) do |menu| %>\n <% menu.with_item(\n label: \"Repository\",\n href: update_repo_grouping_path,\n form_arguments: {\n method: :post,\n name: \"group_by\",\n value: \"repository\"\n }\n ) %>\n<% end %>\n```\n\nMake sure to specify `method: :post`, as the default is `:get`. When clicked, the list item will submit a POST request to\nthe URL passed in the `href:` argument, including a parameter named `\"group_by\"` with a value of `\"repository\"`. If no value\nis given, the name, eg. `\"group_by\"`, will be used as the value.\n\nIt is possible to include multiple fields on submit. Instead of passing the `name:` and `value:` arguments, pass an array via\nthe `inputs:` argument:\n\n```erb\n<%= render(Primer::Alpha::ActionMenu.new) do |menu| %>\n <% menu.with_show_button { \"Group By\" } %>\n <% menu.with_item(\n label: \"Repository\",\n href: update_repo_grouping_path,\n form_arguments: {\n method: :post,\n inputs: [{\n name: \"group_by\",\n value: \"repository\"\n }, {\n name: \"some_other_field\",\n value: \"some value\",\n }],\n }\n ) %>\n<% end %>\n```\n\n### Form arguments\n\nThe following table summarizes the arguments allowed in the `form_arguments:` hash mentioned above.\n\n|Name |Type |Default|Description|\n|:----------------|:-------------|:------|:----------|\n|`method` |`Symbol` |`:get` |The HTTP request method to use to submit the form. One of `:get`, `:post`, `:patch`, `:put`, `:delete`, or `:head`|\n|`name` |`String` |`nil` |The name of the field that will be sent to the server on submit.|\n|`value` |`String` |`nil` |The value of the field that will be sent to the server on submit.|\n|`input_arguments`|`Hash` |`{}` |Additional key/value pairs to emit as HTML attributes on the `<input type=\"hidden\">` element.|\n|`inputs` |`Array<Hash>` |`[]` |An array of hashes representing HTML `<input type=\"hidden\">` elements. Must contain at least `name:` and `value:` keys. If additional key/value pairs are provided, they are emitted as HTML attributes on the `<input>` element. This argument supercedes the `name:`, `value:`, and `:input_arguments` arguments listed above.|\n\nThe elements of the `inputs:` array will be emitted as HTML `<input type=\"hidden\">` elements.\n\n### JavaScript API\n\n`ActionMenu`s render an `<action-menu>` custom element that exposes behavior to the client.\n\n#### Query methods\n\n* `getItemById(itemId: string): Element`: Returns the item's HTML `<li>` element. The return value can be passed as the `item` argument to the other methods listed below.\n* `isItemChecked(item: Element): boolean`: Returns `true` if the item is checked, `false` otherwise.\n* `isItemHidden(item: Element): boolean`: Returns `true` if the item is hidden, `false` otherwise.\n* `isItemDisabled(item: Element): boolean`: Returns `true` if the item is disabled, `false` otherwise.\n\nNOTE: Item IDs are special values provided by the user that are attached to `ActionMenu` items as the `data-item-id`\nHTML attribute. Item IDs can be provided by passing an `item_id:` attribute when adding items to the list, eg:\n\n```erb\n<%= render(Primer::Alpha::ActionMenu.new) do |menu| %>\n <% menu.with_item(item_id: \"my-id\") %>\n<% end %>\n```\n\n#### State methods\n\n* `showItem(item: Element)`: Shows the item, i.e. makes it visible.\n* `hideItem(item: Element)`: Hides the item, i.e. makes it invisible.\n* `enableItem(item: Element)`: Enables the item, i.e. makes it clickable by the mouse and keyboard.\n* `disableItem(item: Element)`: Disables the item, i.e. makes it unclickable by the mouse and keyboard.\n* `checkItem(item: Element)`: Checks the item. Only has an effect in single- and multi-select modes.\n* `uncheckItem(item: Element)`: Unchecks the item. Only has an effect in multi-select mode, since items cannot be unchecked in single-select mode.\n\n#### Events\n\nThe `<action-menu>` element fires an `itemActivated` event whenever an item is activated (eg. clicked) via the mouse or keyboard.\n\n```typescript\ndocument.querySelector(\"action-menu\").addEventListener(\"itemActivated\", (event: CustomEvent<ItemActivatedEvent>) => {\n event.detail.item // Element: the <li> item that was activated\n event.detail.checked // boolean: whether or not the result of the activation checked the item\n})\n```", "accessibility_docs": "The action for the menu item needs to be on the element with `role=\"menuitem\"`. Semantics are removed for everything\nnested inside of it. When a menu item is selected, the menu will close immediately.\n\nAdditional information around the keyboard functionality and implementation can be found on the\n[WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.2/#menu).", "is_form_component": false, "is_published": true, "requires_js": true, "component": "ActionMenu", "status": "alpha", "a11y_reviewed": false, "short_name": "ActionMenu", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/alpha/action_menu.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/alpha/action_menu/default/", "parameters": [ { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "The arguments accepted by {{#link_to_component}}Primer::Alpha::ActionMenu::PrimaryMenu{{/link_to_component}}." } ], "slots": [], "methods": [ { "name": "with_item", "description": "Adds an item to the menu.", "parameters": [ { "name": "system_arguments", "type": "Hash", "default": "N/A", "description": "The arguments accepted by {{#link_to_component}}Primer::Alpha::ActionList{{/link_to_component}}'s `item` slot." } ], "return_types": [] }, { "name": "with_avatar_item", "description": "Adds an avata