Rename form-callout to callout-form-element & adjust docstrings

Author: TheSyscall

asset/css/callout.less

@@ -7,12 +7,12 @@
   width: fit-content;
   margin: 0 auto 1em;
 
-  &.callout-fullwidth {
+  &.callout-full-width {
     width: 100%;
     justify-content: start;
   }
 
-  &.form-callout {
+  &.callout-form-element {
     margin-left: 14em;
     width: auto;
     justify-content: start;

src/Widget/Callout.php

@@ -12,24 +12,32 @@
 
 /**
  * An information box that can be used to display information to the user.
- * It consists of a set of standardized colors and icons that can be used to visually distinguish the type of
- * information.
- * A content string and an optional title can be passed to the constructor.
+ * It consists of a set of standardized colors and icons that can be used to
+ * visually distinguish the type of information. A content string and an
+ * optional title can be passed to the constructor.
  */
 class Callout extends BaseHtmlElement
 {
     use Translation;
 
+    /** @var string Classname for form-element callouts */
+    protected const CLASS_FORM_ELEMENT = 'callout-form-element';
+
+    /** @var string Classname for full-width callouts */
+    protected const CLASS_FULL_WIDTH = 'callout-full-width';
+
     protected $tag = 'div';
 
     protected $defaultAttributes = ['class' => 'callout'];
 
     /**
      * Create a new callout
      *
-     * @param CalloutType $type the type of the callout. The type determines the color and icon that is used.
-     * @param ValidHtml|string $content the content of the callout
-     * @param string|null $title an optional title, displayed above the content
+     * The $type parameter determines the color and icon of the callout.
+     *
+     * @param CalloutType $type The type of the callout.
+     * @param ValidHtml|string $content The content of the callout
+     * @param string|null $title An optional title, displayed above the content
      */
     public function __construct(
         protected CalloutType $type,
@@ -56,25 +64,29 @@ protected function assemble(): void
     }
 
     /**
-     * Callouts are only as wide as their content.
+     * Set the callout width to be 100% of its parent container
+     *
+     * Callouts are normally only as wide as their content.
      * Setting it to fullwidth will force the callout to be as wide as its container.
      *
-     * @param bool $fullwidth Whether the callout should be full width
+     * @param bool $isFullWidth Whether the callout should be full width
      *
      * @return $this
      */
-    public function setFullwidth(bool $fullwidth = true): static
+    public function setFullwidth(bool $isFullWidth = true): static
     {
-        if ($fullwidth) {
-            $this->addAttributes(Attributes::create(['class' => 'callout-fullwidth']));
+        if ($isFullWidth) {
+            $this->addAttributes(Attributes::create(['class' => static::CLASS_FULL_WIDTH]));
         } else {
-            $this->removeAttribute('class', 'callout-fullwidth');
+            $this->removeAttribute('class', static::CLASS_FULL_WIDTH);
         }
 
         return $this;
     }
 
     /**
+     * Set up the callout to be used inside a form
+     *
      * Setting this to true will allow the callout to be used for a single form element.
      * This is used to visually align the callout to the content of the form element.
      *
@@ -85,9 +97,9 @@ public function setFullwidth(bool $fullwidth = true): static
     public function setFormElement(bool $isFormElement = true): static
     {
         if ($isFormElement) {
-            $this->addAttributes(Attributes::create(['class' => 'form-callout']));
+            $this->addAttributes(Attributes::create(['class' => static::CLASS_FORM_ELEMENT]));
         } else {
-            $this->removeAttribute('class', 'form-callout');
+            $this->removeAttribute('class', static::CLASS_FORM_ELEMENT);
         }
 
         return $this;