@primer/view-components 0.36.6-rc.f22d48ee → 0.37.0-rc.1b825e45

package/app/components/primer/beta/details_toggle_element.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A companion Catalyst element for the Details view component. This element
+ * ensures the <details> and <summary> elements markup is properly accessible by
+ * updating the aria-label and aria-expanded attributes on click.
+ *
+ * aria-label values default to "Expand" and "Collapse". To override those
+ * values, use the `data-aria-label-open` and `data-aria-label-closed`
+ * attributes on the summary target.
+ *
+ * @example
+ * ```html
+ * <details-toggle>
+ *   <details open=true data-target="details-toggle.detailsTarget">
+ *     <summary
+ *       aria-expanded="true"
+ *       aria-label="Collapse me"
+ *       data-target="details-toggle.summaryTarget"
+ *       data-action="click:details-toggle#toggle"
+ *       data-aria-label-closed="Expand me"
+ *       data-aria-label-open="Collapse me"
+ *     >
+ *       Click me
+ *     </summary>
+ *     <div>Contents</div>
+ *   </details>
+ * </details-toggle>
+ * ```
+ */
+declare class DetailsToggleElement extends HTMLElement {
+    detailsTarget: HTMLDetailsElement;
+    summaryTarget: HTMLElement;
+    toggle(): void;
+}
+declare global {
+    interface Window {
+        DetailsToggleElement: typeof DetailsToggleElement;
+    }
+}
+export {};

package/app/components/primer/beta/details_toggle_element.js

@@ -0,0 +1,60 @@
+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;
+};
+import { controller, target } from '@github/catalyst';
+/**
+ * A companion Catalyst element for the Details view component. This element
+ * ensures the <details> and <summary> elements markup is properly accessible by
+ * updating the aria-label and aria-expanded attributes on click.
+ *
+ * aria-label values default to "Expand" and "Collapse". To override those
+ * values, use the `data-aria-label-open` and `data-aria-label-closed`
+ * attributes on the summary target.
+ *
+ * @example
+ * ```html
+ * <details-toggle>
+ *   <details open=true data-target="details-toggle.detailsTarget">
+ *     <summary
+ *       aria-expanded="true"
+ *       aria-label="Collapse me"
+ *       data-target="details-toggle.summaryTarget"
+ *       data-action="click:details-toggle#toggle"
+ *       data-aria-label-closed="Expand me"
+ *       data-aria-label-open="Collapse me"
+ *     >
+ *       Click me
+ *     </summary>
+ *     <div>Contents</div>
+ *   </details>
+ * </details-toggle>
+ * ```
+ */
+let DetailsToggleElement = class DetailsToggleElement extends HTMLElement {
+    toggle() {
+        const detailsIsOpen = this.detailsTarget.hasAttribute('open');
+        if (detailsIsOpen) {
+            const ariaLabelClosed = this.summaryTarget.getAttribute('data-aria-label-closed') || 'Expand';
+            this.summaryTarget.setAttribute('aria-label', ariaLabelClosed);
+            this.summaryTarget.setAttribute('aria-expanded', 'false');
+        }
+        else {
+            const ariaLabelOpen = this.summaryTarget.getAttribute('data-aria-label-open') || 'Collapse';
+            this.summaryTarget.setAttribute('aria-label', ariaLabelOpen);
+            this.summaryTarget.setAttribute('aria-expanded', 'true');
+        }
+    }
+};
+__decorate([
+    target
+], DetailsToggleElement.prototype, "detailsTarget", void 0);
+__decorate([
+    target
+], DetailsToggleElement.prototype, "summaryTarget", void 0);
+DetailsToggleElement = __decorate([
+    controller
+], DetailsToggleElement);
+window.DetailsToggleElement = DetailsToggleElement;

package/app/components/primer/primer.d.ts

@@ -25,3 +25,4 @@ import '../../lib/primer/forms/primer_text_field';
 import '../../lib/primer/forms/toggle_switch_input';
 import './alpha/action_menu/action_menu_element';
 import './alpha/select_panel_element';
+import './beta/details_toggle_element';

package/app/components/primer/primer.js

@@ -25,3 +25,4 @@ import '../../lib/primer/forms/primer_text_field';
 import '../../lib/primer/forms/toggle_switch_input';
 import './alpha/action_menu/action_menu_element';
 import './alpha/select_panel_element';
+import './beta/details_toggle_element';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/view-components",
-  "version": "0.36.6-rc.f22d48ee",
+  "version": "0.37.0-rc.1b825e45",
   "description": "ViewComponents for the Primer Design System",
   "main": "app/assets/javascripts/primer_view_components.js",
   "module": "app/components/primer/primer.js",

package/static/arguments.json

@@ -1253,6 +1253,12 @@
         "default": "`false`",
         "description": "When set to `true`, the form control will take up all the horizontal space allowed by its container."
       },
+      {
+        "name": "label_arguments",
+        "type": "Hash",
+        "default": "`{}`",
+        "description": "HTML attributes to attach to the `<label>` element that labels the input."
+      },
       {
         "name": "system_arguments",
         "type": "Hash",

package/static/constants.json

@@ -333,6 +333,8 @@
     ]
   },
   "Primer::Alpha::Dropdown": {
+    "ARIA_LABEL_CLOSED_DEFAULT": "Open",
+    "ARIA_LABEL_OPEN_DEFAULT": "Close",
     "GeneratedSlotMethods": "Primer::Alpha::Dropdown::GeneratedSlotMethods",
     "Menu": "Primer::Alpha::Dropdown::Menu"
   },
@@ -1037,6 +1039,8 @@
     ]
   },
   "Primer::Beta::Details": {
+    "ARIA_LABEL_CLOSED_DEFAULT": "Expand",
+    "ARIA_LABEL_OPEN_DEFAULT": "Collapse",
     "BODY_TAG_DEFAULT": "div",
     "BODY_TAG_OPTIONS": [
       "ul",

package/static/info_arch.json

@@ -2838,7 +2838,7 @@
     "description": "Check boxes are true/false inputs rendered as `<input type=\"checkbox\">` in HTML.\n\n## Schemes\n\nCheck boxes can submit values to the server using one of two schemes, either `:array`\nor `:boolean` (the default). Check boxes with a scheme of `:boolean` function like normal\nHTML check boxes. If they are checked, a value of \"1\" is sent to the server; if they are\nunchecked, a value of \"0\" is sent to the server. The checked and unchecked values can be\ncustomized via the `:value` and `:unchecked_value` arguments respectively.\n\nWhereas `:boolean` check boxes must have unique names, `:array` check boxes all have the\nsame name. On form submission, Rails will aggregate the values of the check boxes with the\nsame name and provide them to the controller as an array. If `:scheme:` is `:array`, the\n`:value` argument must also be provided. The `:unchecked_value` argument is ignored. If a\ncheck box is checked on submit, its corresponding value will appear in the array. If it is\nnot checked, its value will not appear in the array.\n\n## Caption templates\n\nCaption templates for `:array`-type check boxes work a little differently than they do for\nother input types. Because the name must be the same for all check boxes that make up an\narray, caption template file names are comprised of both the name _and_ the value of each\ncheck box. For example, a check box with the name `foo` and value `bar` must have a caption\ntemplate named `foo_bar_caption.html.erb`.\n\n## Nested Forms\n\nCheck boxes can have \"nested\" forms that are rendered below the caption. A common use-case\nis a form that is hidden until the check box is checked. Nested forms are indented slightly\nto align with the label and caption.\n\nDefine a nested form via the `#nested_form` method, which is expected to return an instance\nof a Primer form (see the usage section below).\n\nAny fields defined in the nested form are submitted along with the parent form's fields.\n\n**NOTE**: Check boxes do not automatically show or hide nested forms. If such behavior is\ndesired, it must be done by hand.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "CheckBox",
     "status": "alpha",
@@ -3075,7 +3075,7 @@
     "description": "Check box groups consist of one or more related check boxes.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "CheckBoxGroup",
     "status": "alpha",
@@ -3843,7 +3843,18 @@
         "name": "button",
         "description": "Required trigger for the dropdown. Has the same arguments as {{#link_to_component}}Primer::ButtonComponent{{/link_to_component}},\nbut it is locked as a `summary` tag.",
         "parameters": [
-
+          {
+            "name": "aria_label_open",
+            "type": "String",
+            "default": "N/A",
+            "description": "Defaults to \"Close\". Value to announce when menu is open."
+          },
+          {
+            "name": "aria_label_closed",
+            "type": "String",
+            "default": "N/A",
+            "description": "Defaults to \"Open\". Value to announce when menu is closed."
+          }
         ]
       },
       {
@@ -4195,7 +4206,7 @@
     "description": "A button input rendered using the HTML `<button type=\"button\">` tag.\n\nThis component wraps the Primer button component and supports the same slots and arguments.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "FormButton",
     "status": "alpha",
@@ -4268,9 +4279,9 @@
   },
   {
     "fully_qualified_name": "Primer::Alpha::FormControl",
-    "description": "Wraps an input (or arbitrary content) with a label above and a caption and validation message beneath.\nNOTE: This `FormControl` component is designed for wrapping inputs that aren't supported by the Primer\nforms framework.",
-    "accessibility_docs": null,
-    "is_form_component": false,
+    "description": "Wraps an input (or arbitrary content) with a label above and a caption and validation message beneath.\n\nNOTE: This `FormControl` component is designed for wrapping inputs that aren't supported by the Primer\nforms framework.",
+    "accessibility_docs": "Because `FormControl` does not manage the actual `<input>` element, it cannot semantically connect\nthe input and its associated label. For this and other reasons, consumers are highly encouraged to\nuse Primer's pre-made form components like `TextField`, etc, ideally via the Primer forms framework.\n\nUsers of the `FormControl` component will need to manually connect the label using the `for:`\nattribute, eg:\n\n```erb\n<%= form_with(url: \"/path/somewhere\") do |f| %>\n  <%= render(Primer::Alpha::FormControl.new(label_arguments: { for: \"bar\" })) do |component| %>\n    <% component.with_input do |input_arguments| %>\n      <%= f.text_field(:bar, **input_arguments) %>\n    <% end %>\n  <% end %>\n<% end %>\n```\n\nNote that the name of the field, `:bar`, is passed to both the Rails `#text_field` method _and_\nas part of the `label_arguments` passed to the `FormControl` constructor.\n\nSimilarly, `FormControl` cannot automatically connect the `<input>` element to the caption and\nvalidation message elements. The component attempts to mitigate this by including the correct\n`aria-describedby` attribute in the hash it yields to the block passed to `#with_input`. In the\nexample above, `input_arguments[:aria][:describedby]` contains the HTML IDs for both the caption\nand validation message elements, and can be passed directly to Rails' form helper methods. If the\ninput being wrapped is not generated by a Rails form helper, care must be taken to set\n`aria-describedby` manually on the input element.",
+    "is_form_component": true,
     "is_published": true,
     "requires_js": false,
     "component": "FormControl",
@@ -4316,6 +4327,12 @@
         "default": "`false`",
         "description": "When set to `true`, the form control will take up all the horizontal space allowed by its container."
       },
+      {
+        "name": "label_arguments",
+        "type": "Hash",
+        "default": "`{}`",
+        "description": "HTML attributes to attach to the `<label>` element that labels the input."
+      },
       {
         "name": "system_arguments",
         "type": "Hash",
@@ -4340,7 +4357,36 @@
       }
     ],
     "methods": [
+      {
+        "name": "required?",
+        "description": "Whether or not this input is marked as required.",
+        "parameters": [
+
+        ],
+        "return_types": [
+          "Boolean"
+        ]
+      },
+      {
+        "name": "visually_hide_label?",
+        "description": "Whether or not to hide the label visually. The label will still be visible to screen readers.",
+        "parameters": [
 
+        ],
+        "return_types": [
+          "Boolean"
+        ]
+      },
+      {
+        "name": "full_width?",
+        "description": "Whether or not the form control should take up all the horizontal space allowed by its container.",
+        "parameters": [
+
+        ],
+        "return_types": [
+          "Boolean"
+        ]
+      }
     ],
     "previews": [
       {
@@ -5164,7 +5210,7 @@
     "description": "Multi inputs are comprised of multiple constituent fields, only one of which is visible\nat a given time. They are designed for situations where constituent inputs are shown or\nhidden based on the value of another field. For example, consider an address form. If\nthe user chooses the USA as the country, the region input should show a list of states\nand US territories; if the user instead chooses Canada, the region input should show a\nlist of Canadian provinces, etc.\n\nUnlike everywhere else in Primer forms, constituent inputs are not directly passed a\n`name` attribute. Instead, developers pass a `name` attribute to the multi input itself.\nThe multi input then automatically assigns each constituent input the same name. This is\ndone so that the multi input looks like a single field from the server's point of view.\nUsing the address form example from earlier, this means only one value - either a US state\nor a Canadian provice - will be submitted to the server under the `region` key.\n\nActually, that's not quite true. Constituent inputs _are_ given a `name`, but it's added to\nthe input as the `data-name` attribute as a way to identify constituent inputs, and will not\nbe sent to the server.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": true,
     "component": "MultiInput",
     "status": "alpha",
@@ -6373,7 +6419,7 @@
     "description": "Radio buttons represent one of a set of options and are rendered as `<input type=\"radio\">` in HTML.\n**NOTE**: You probably want to use the {{#link_to_component}}Primer::Alpha::RadioButtonGroup{{/link_to_component}}\ncomponent instead, as it allows rendering a group of options.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "RadioButton",
     "status": "alpha",
@@ -6586,7 +6632,7 @@
     "description": "A group of mutually exclusive radio buttons.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "RadioButtonGroup",
     "status": "alpha",
@@ -7099,7 +7145,7 @@
     "description": "Select lists are single-line text inputs rendered as `<select>` tags in HTML.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "Select",
     "status": "alpha",
@@ -8297,7 +8343,7 @@
     "description": "A submit button input rendered using the HTML `<button type=\"submit\">` tag.\n\nThis component wraps the Primer button component and supports the same slots and arguments.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "SubmitButton",
     "status": "alpha",
@@ -8670,7 +8716,7 @@
     "description": "Text areas are multi-line text inputs rendered using the `<textarea>` tag in HTML.",
     "accessibility_docs": null,
     "is_form_component": true,
-    "is_published": false,
+    "is_published": true,
     "requires_js": false,
     "component": "TextArea",
     "status": "alpha",
@@ -8929,7 +8975,7 @@
     "accessibility_docs": null,
     "is_form_component": true,
     "is_published": true,
-    "requires_js": false,
+    "requires_js": true,
     "component": "TextField",
     "status": "alpha",
     "a11y_reviewed": false,
@@ -13358,9 +13404,26 @@
     "slots": [
       {
         "name": "summary",
-        "description": null,
+        "description": "Use the Summary slot as the target for toggling the Details content open/closed.",
         "parameters": [
-
+          {
+            "name": "button",
+            "type": "Boolean",
+            "default": "N/A",
+            "description": "Whether or not to render the summary element as a button."
+          },
+          {
+            "name": "aria_label_open",
+            "type": "String",
+            "default": "N/A",
+            "description": "Defaults to \"Collapse\". Value to announce when details element is open."
+          },
+          {
+            "name": "aria_label_closed",
+            "type": "String",
+            "default": "N/A",
+            "description": "Defaults to \"Expand\". Value to announce when details element is closed."
+          }
         ]
       },
       {
@@ -13401,6 +13464,26 @@
         ],
         "return_types": [
 
+        ]
+      },
+      {
+        "name": "open",
+        "description": "Returns the value of attribute open.",
+        "parameters": [
+
+        ],
+        "return_types": [
+
+        ]
+      },
+      {
+        "name": "open?",
+        "description": "Returns the value of attribute open.",
+        "parameters": [
+
+        ],
+        "return_types": [
+
         ]
       }
     ],
@@ -13456,6 +13539,19 @@
             "color-contrast"
           ]
         }
+      },
+      {
+        "preview_path": "primer/beta/details/open",
+        "name": "open",
+        "snapshot": "false",
+        "skip_rules": {
+          "wont_fix": [
+            "region"
+          ],
+          "will_fix": [
+            "color-contrast"
+          ]
+        }
       }
     ],
     "subcomponents": [
@@ -14661,7 +14757,7 @@
       },
       {
         "name": "render_outer_list?",
-        "description": "Lists that contain top-level items (i.e. items outside of a group) should be wrapped in a <ul>",
+        "description": "Lists that contain top-level items (i.e. items outside of a group) should be wrapped in a `<ul>`",
         "parameters": [
 
         ],

package/static/previews.json

@@ -3118,6 +3118,19 @@
             "color-contrast"
           ]
         }
+      },
+      {
+        "preview_path": "primer/beta/details/open",
+        "name": "open",
+        "snapshot": "false",
+        "skip_rules": {
+          "wont_fix": [
+            "region"
+          ],
+          "will_fix": [
+            "color-contrast"
+          ]
+        }
       }
     ]
   },