Integrate reply Comment Form into Comment pattern (#1423)

The primary focus of this PR is integrating the Comment Form for replies into the Comment pattern.

While I was working on this I made some changes to the Comment Form component and updated the code examples for all the Comment stories.

Author: Paul-Hebert

.changeset/grumpy-dancers-jump.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': minor
+---
+
+Add reply forms to comments

src/components/comment-form/comment-form.stories.mdx

@@ -24,7 +24,7 @@ const tyler = {
 
 # Comment Form
 
-The form used to add a comment to an article.
+The form used to add a comment to an article. Including the `heading_id` and `help_text_id` properties will provide assistive technologies additional context.
 
 <Canvas>
   <Story
@@ -34,7 +34,11 @@ The form used to add a comment to an article.
       docs: {
         source: {
           code: makeTwigInclude(
-            '@cloudfour/components/comment-form/comment-form.twig'
+            '@cloudfour/components/comment-form/comment-form.twig',
+            {
+              heading_id: 'leave-a-comment',
+              help_text_id: 'leave-a-comment-help-text',
+            }
           ),
         },
       },
@@ -51,12 +55,14 @@ The form used to add a comment to an article.
         logged_in_user: isLoggedIn ? tyler : undefined,
         log_out_url: '/logout',
         is_reply: isReply,
+        heading_id: 'leave-a-comment',
+        help_text_id: 'leave-a-comment-help-text',
       });
     }}
   </Story>
 </Canvas>
 
-There is also a reply version of this component (`is_reply: true`), used to reply to an existing comment:
+There is also a reply version of this component (`is_reply: true`), used to reply to an existing comment. (You'll also want to modify `heading_tag`, `heading_id`, `heading_class`, and `heading_text`. When using the [Comment pattern](/docs/components-comment--with-reply-button) this will be done automatically.)
 
 <Canvas>
   <Story
@@ -67,7 +73,16 @@ There is also a reply version of this component (`is_reply: true`), used to repl
         source: {
           code: makeTwigInclude(
             '@cloudfour/components/comment-form/comment-form.twig',
-            { logged_in_user: tyler, log_out_url: '/logout', is_reply: true }
+            {
+              logged_in_user: tyler,
+              log_out_url: '/logout',
+              is_reply: true,
+              heading_id: 'reply-to-comment-100',
+              heading_tag: 'h4',
+              heading_text: 'Reply to John Doe',
+              heading_class: 'u-hidden-visually',
+              main_label: 'Reply',
+            }
           ),
         },
       },
@@ -84,6 +99,11 @@ There is also a reply version of this component (`is_reply: true`), used to repl
         logged_in_user: isLoggedIn ? tyler : undefined,
         log_out_url: '/logout',
         is_reply: isReply,
+        heading_id: 'reply-to-comment-100',
+        heading_tag: 'h4',
+        heading_text: 'Reply to John Doe',
+        heading_class: 'u-hidden-visually',
+        main_label: 'Reply',
       });
     }}
   </Story>
@@ -92,6 +112,12 @@ There is also a reply version of this component (`is_reply: true`), used to repl
 ## Template Properties
 
 - `class`: Append a class to the root element.
+- `heading_id`: A unique ID for your heading element. This will be used as the accessible name for the form.
+- `heading_tag`: The tag for your heading (defaults to `h2`).
+- `heading_text`: The text for your heading.
+- `heading_class`: An optional class for your heading.
+- `heading_id`: A unique ID for your help text. This will be used as the accessible description for the reply textarea.
+- `main_label`: The label for the primary message textarea. Defaults to `message`
 - `logged_in_user`: [user object](https://timber.github.io/docs/reference/timber-user/#properties) of the type:
 
   ```ts
@@ -107,4 +133,4 @@ There is also a reply version of this component (`is_reply: true`), used to repl
 
 ## JavaScript
 
-The Comment Form component includes the [Elastic Textarea component](http://localhost:6006/?path=/docs/components-input--elastic-textarea). See the Elastic Textarea component for JavaScript setup details.
+The Comment Form component includes the [Elastic Textarea component](/docs/components-input--elastic-textarea). See the Elastic Textarea component for JavaScript setup details.

src/components/comment-form/comment-form.twig

@@ -1,15 +1,34 @@
 <form
   class="c-comment-form{% if class %} {{class}}{% endif %}"
+  {% if heading_id %}aria-labelledby="{{ heading_id }}"{% endif %}
   {%- if action %}action="{{ action }}"{% endif -%}
   {%- if method %}method="{{ method }}"{% endif -%}
 >
   {% block prompt %}
-  <h2>Leave a Comment</h2>
-  <p>Please be kind, courteous and constructive. You may use simple HTML or <a href="https://en.support.wordpress.com/markdown-quick-reference">Markdown</a> in your comments. All fields are required.</p>
+    {% set _heading_tag = heading_tag|default('h2') %}
+    <{{_heading_tag}}
+      {% if heading_id %}id="{{ heading_id }}"{% endif %}
+      {% if heading_class %}class="{{ heading_class }}"{% endif %}
+    >
+      {{ heading_text|default("Leave a Comment") }}
+    </{{_heading_tag}}>
+    <p {% if help_text_id %}id="{{ help_text_id }}"{% endif %}>
+      Please be kind, courteous and constructive.
+      You may use simple HTML or
+      <a href="https://en.support.wordpress.com/markdown-quick-reference">Markdown</a>
+      in your comments.
+      All fields are required.
+    </p>
   {% endblock %}
-  {% embed '@cloudfour/objects/form-group/form-group.twig' with { label: 'Message' } only %}
+  {% embed '@cloudfour/objects/form-group/form-group.twig' with { label: main_label|default('Message') } %}
     {% block control %}
-      {% include '@cloudfour/components/input/input.twig' with { type: 'textarea', name: 'comment', required: true, class: 'c-input--elastic js-elastic-textarea' } only %}
+      {% include '@cloudfour/components/input/input.twig' with {
+        type: 'textarea',
+        name: 'comment',
+        required: true,
+        class: 'c-input--elastic js-elastic-textarea',
+        'aria-describedby': help_text_id
+      } only %}
     {% endblock %}
   {% endembed %}
   {% if logged_in_user and log_out_url %}
@@ -34,10 +53,10 @@
     {% embed '@cloudfour/objects/button-group/button-group.twig' only %}
       {% block content %}
         {% include '@cloudfour/components/button/button.twig' with { label: 'Submit Reply' } only %}
-        {% include '@cloudfour/components/button/button.twig' with { label: 'Cancel', class: 'c-button--secondary' } only %}
+        {% include '@cloudfour/components/button/button.twig' with { label: 'Cancel', class: 'c-button--secondary js-cancel-reply' } only %}
       {% endblock %}
     {% endembed %}
   {% else %}
     {% include '@cloudfour/components/button/button.twig' with { label: 'Submit Comment' } only %}
   {% endif %}
-</div>
+</form>

src/components/comment/comment.scss

@@ -23,6 +23,7 @@
 
 /// Display a vertical line if the comment contains a reply thread to connect
 /// those comments visually with their parent.
+.c-comment.is-replying::after,
 .c-comment--thread::after {
   border-radius: size.$border-radius-full;
   content: '';
@@ -42,6 +43,15 @@
   }
 }
 
+/// Comment reply forms are hidden until someone starts a reply.
+.c-comment__reply-form {
+  display: none;
+}
+
+.c-comment.is-replying .c-comment__reply-form {
+  display: block;
+}
+
 /// Named object for consistency with the Media component.
 .c-comment__object {
   grid-area: object;
@@ -124,6 +134,10 @@
   // Visually centers the child avatars with the indentation of the parent
   // comment. Without this, the replies feel nested too far to the right.
   margin-left: math.div(size.$square-avatar-small, -2);
+}
+
+.c-comment__replies,
+.c-comment__reply-form {
   // Since the replies are likely wrapped in a Rhythm object intended to inherit
   // the parent rhythm, we can use that custom property to inherit that same
   // spacing between the meta and replies.