Provide a checkout pane for customer comments

The token could use the generated logs, but wondering whether storing the comment in an actual separate field doesn't make this easier?
That makes it less custom, and easier to print in Twig template without additional magic / logic required...

But not 100% sure the field is the right solution either, it does simplify the code / logic for sure.

I initially extracted code from #3267366: Add customer-facing order comments, but I'm having second thoughts about the approach.
With the current approach, there is no way to have customer comments in checkout without the commerce_log module enabled... I don't think we must require commerce_log for that?

The checkout pane is provided by the commerce_log module. Then, if we want to include the comments in the order receipt, we need to have conditional logic based on whether the commerce_log module is installed...

There was a method added to the OrderReceiptMail:

  /**
   * Get customer viewable order comments.
   *
   * @param \Drupal\commerce_order\Entity\OrderInterface $order
   *   The order entity.
   *
   * @return array
   *   The order comments.
   */
  public function getOrderComments(OrderInterface $order): array {
    $orderComments = [];
    if (\Drupal::moduleHandler()->moduleExists('commerce_log')) {
      $logStorage = \Drupal::entityTypeManager()->getStorage('commerce_log');
      /** @var \Drupal\commerce_log\Entity\LogInterface $logEntry */
      foreach (array_reverse($logStorage->loadMultipleByEntity($order)) as $logEntry) {
        if ($logEntry->getTemplateId() === 'commerce_order_to_customer_comment') {
          $orderComments[$logEntry->id()]['type'] = OrderCommentEvent::ORDER_TO_CUSTOMER_COMMENT;
          $orderComments[$logEntry->id()]['date'] = $logEntry->getCreatedTime();
          $orderComments[$logEntry->id()]['comment'] = $logEntry->getParams()['comment'];
        }<ol>
  <li></li>
</ol>
        elseif ($logEntry->getTemplateId() === 'commerce_order_from_customer_comment') {
          $orderComments[$logEntry->id()]['type'] = OrderCommentEvent::ORDER_FROM_CUSTOMER_COMMENT;
          $orderComments[$logEntry->id()]['date'] = $logEntry->getCreatedTime();
          $orderComments[$logEntry->id()]['comment'] = $logEntry->getParams()['comment'];
        }
      }
    }

    return $orderComments;
  }

I don't think we have to do it this way, we could implement a hook_preprocess_HOOK() from the commerce_log module.

So I think we have several options:

1. Perhaps we should move the checkout pane to the checkout module?
2. The order receipt is looping on order comments, but if we have a single pane and ignore admin comments, I don't think this is necessary and we should just focus on the order comments entered in checkout?
3. Maybe we should define an actual base field for the customer comments after all? My problem with the current approach is that the order receipt is updated only if the commerce_log module is enabled, so if I define the checkout pane from the checkout module, then there is an inconsistency, we may expose a pane and not do anything with the comment entered...

Considering this is a checkout feature, I think the checkout module should be responsible for providing it, so I'm thinking of:

• A new base field provided by the checkout module ("checkout_comments")
• Commerce log could still record a log on checkout completion
• The pane manipulates the field
• The order receipt simply outputs the field value? Though the patch from #3267366: Add customer-facing order comments also includes a date, which wouldn't be possible if we don't rely on the logs for the order receipt...

Thoughts?

After discussing this with @rszrama on Slack, decided to implement the original approach.
The MR is a simplified version of the changes from #3267366: Add customer-facing order comments with several adjustments:

1. No "to customer" log template
2. The order receipt simply outputs the order_comments variable, the HTML is coming from a new template/theme function "commerce_log_order_receipt_customer_comments" provided by the commerce_log module
3. I removed all the commerce_log code that was added to the OrderReceipt email, all that logic now lives in a preprocess within the commerce_log module (commerce_log_preprocess_commerce_order_receipt)
4. There is no custom event, no custom permission.

The MR focuses on the checkout pane, generating the log on checkout completion as well as outputting the customer comments in the order receipt (see the attached screenshot).

In the event we're adding "to customer" comments, the current approach might not be flexible enough but I'm not sure (especially the template part).
I removed the log date from the order receipt template, and I'm not looping on logs since there is supposed to be only one customer comment.

At the same time, and maybe I'm missing something, I don't really understand in which context an admin would leave comments to a customer from the admin, PRIOR to the order being placed?

Crediting

Actually, after rediscussing this with @rszrama, it might make more sense to implement a solution that is more aligned with my comment #9.
But now thinking we should stick to "customer_comments", to support Headless and setting a comment via JSONAPI for example.

In this case, the field could be defined as a base field from the order module directly I suppose?

The second problem isn't addressed here, the point of this issue is to focus on customer comments, left during checkout.
The goal was to split the changes into smaller chunks so this can more easily get in.

Wanted to point out, after discussing this internally, that an alternative to this would be to use https://www.drupal.org/project/commerce_checkout_order_fields.

Ok, we now have a base "customer_comments" field, it is used in the order receipt. The log module is still logging the message in the activity log. The pane is provided by commerce_checkout, and the field can be added to the order view (it's currently output under "Other").

I'm wondering if this should be 3.x only or whether I should backport this change to 2.x, this affects the update hook number ofc, so we have to make a decision.

@rszrama: Last thing... Should we use plural or singular? "customer_comments" might suggest the field cardinality is multiple...

So the question is: "customer_comment" vs "customer_comments", for the field / checkout pane ID as well as the order receipt.

@morbu iff: Yes only customer comments in checkout, and the comment is logged in the activity log. I tried simplifying this as much as possible so we could get at least part of the functionality in. The other issue kind of derailed with events / templates as well as commerce_log code in the multiple modules (OrderReceipt fetching implicitly depending on commerce_log etc)...

I didn't like the fact that commerce_log had to be installed in order to get the checkout pane for example...

Just FYI, I kept the same template ID for the log as in the original patch (commerce_order_from_customer_comment).
We can always find a way to merge the two functionalities together somehow, but let's connect on Slack whenever you have a moment, or perhaps this is something we could discuss in Barcelona, in case you're travelingt to Drupalcon.