From 6825a49f36d9d4351fd27c57df7f66e2e9793cbb Mon Sep 17 00:00:00 2001
From: Alexandr Chernyaev <bliz48rus@gmail.com>
Date: Tue, 29 Oct 2024 00:26:16 +0300
Subject: [PATCH] Change method and improve comments (example)

---
 resources/views/fields/group.blade.php |  2 +-
 src/Screen/Fields/Group.php            | 92 ++++++++++++++++++++++----
 2 files changed, 80 insertions(+), 14 deletions(-)

diff --git a/resources/views/fields/group.blade.php b/resources/views/fields/group.blade.php
index 08909a194..ac4e0f527 100644
--- a/resources/views/fields/group.blade.php
+++ b/resources/views/fields/group.blade.php
@@ -1,7 +1,7 @@
 <div class="d-flex flex-column grid d-md-grid form-group {{ $align }}"
     @style([
         '--bs-columns: '.count($group),
-        'grid-template-columns: '. $gridTemplateColumns => $gridTemplateColumns !== null,
+        'grid-template-columns: '. $widthColumns => $widthColumns !== null,
     ])>
     @foreach($group as $field)
         <div class="{{ $class }}
diff --git a/src/Screen/Fields/Group.php b/src/Screen/Fields/Group.php
index 8b4b807d5..98a3f778a 100644
--- a/src/Screen/Fields/Group.php
+++ b/src/Screen/Fields/Group.php
@@ -20,7 +20,7 @@ class Group implements Fieldable, Groupable
         'class'               => 'col-12 col-md form-group mb-md-0',
         'align'               => 'align-items-baseline',
         'itemToEnd'           => false,
-        'gridTemplateColumns' => null,
+        'widthColumns'        => null,
     ];
 
     /**
@@ -68,31 +68,77 @@ public function render()
     }
 
     /**
-     * Columns only take up as much space as needed.
+     * Set the columns to automatically size based on their content.
+     *
+     * This method configures the columns to only take up as much width
+     * as needed for their content. It achieves this by using the `max-content`
+     * value in a CSS grid template, allowing each column to adjust dynamically
+     * according to the size of its content.
+     *
+     * The number of columns is determined by counting the elements in the group,
+     * and a repeat function is used to apply `max-content` for each column.
+     *
+     * @return $this Returns the current instance for method chaining.
      */
     public function autoWidth(): self
     {
         $countColumns = count($this->get('group'));
 
-        return $this->set('gridTemplateColumns', sprintf('repeat(%s, max-content)', $countColumns));
+        return $this->set('widthColumns', sprintf('repeat(%s, max-content)', $countColumns));
     }
 
     /**
-     * Columns occupy the entire width of the screen.
+     * Set the columns to occupy the entire width of the screen.
+     *
+     * This method configures the columns to utilize the full available width,
+     * effectively making them span across the entire width of the container.
+     * By setting the width columns to null, it allows for a responsive layout
+     * that adjusts based on screen size.
+     *
+     * @return $this Returns the current instance for method chaining.
      */
     public function fullWidth(): self
     {
-        return $this->set('gridTemplateColumns', null);
+        return $this->set('widthColumns', null);
     }
 
     /**
-     * @param string $template
+     * Set the width of the columns using a CSS grid template.
      *
-     * @return $this
+     * This method allows you to define the column widths in a flexible way
+     * by specifying a CSS grid template string. The template can include
+     * various units such as percentages, pixels, or fractional units (fr).
+     *
+     * Example usage:
+     * ```
+     * // Define two columns with a 2:1 ratio
+     * $group->widthColumns('8fr 4fr');
+     *
+     * // Set columns to specific pixel widths
+     * $group->widthColumns('120px 300px');
+     *
+     * // Define columns with percentage widths
+     * $group->widthColumns('30% 70%');
+     *
+     * // Use maximum content width for each column
+     * $group->widthColumns('max-content max-content');
+     *
+     * // Create three equal columns
+     * $group->widthColumns('1fr 1fr 1fr');
+     *
+     * // Use repeat to create four equal columns
+     * $group->widthColumns('repeat(4, 1fr)');
+     * ```
+     *
+     * @param string $template A string representing the CSS grid template
+     *                         for the column widths. This should conform
+     *                         to the CSS `grid-template-columns` specification.
+     *
+     * @return $this Returns the current instance for method chaining.
      */
-    public function gridTemplateColumns(string $template): self
+    public function widthColumns(string $template): self
     {
-        return $this->set('gridTemplateColumns', $template);
+        return $this->set('widthColumns', $template);
     }
 
     /**
@@ -133,7 +179,12 @@ public function form(string $name): self
     }
 
     /**
-     * @return $this
+     * Align columns along their baseline.
+     *
+     * This method sets the vertical alignment of the columns to the baseline,
+     * ensuring that the text aligns according to the baseline of the content.
+     *
+     * @return $this Returns the current instance for method chaining.
      */
     public function alignBaseLine(): self
     {
@@ -141,7 +192,12 @@ public function alignBaseLine(): self
     }
 
     /**
-     * @return $this
+     * Center align columns vertically.
+     *
+     * This method sets the vertical alignment of the columns to the center,
+     * ensuring that all columns are aligned in the middle of the container.
+     *
+     * @return $this Returns the current instance for method chaining.
      */
     public function alignCenter(): self
     {
@@ -149,7 +205,12 @@ public function alignCenter(): self
     }
 
     /**
-     * @return $this
+     * Align columns to the end of the container.
+     *
+     * This method sets the vertical alignment of the columns to the end,
+     * positioning all columns at the bottom of the container.
+     *
+     * @return $this Returns the current instance for method chaining.
      */
     public function alignEnd(): self
     {
@@ -157,7 +218,12 @@ public function alignEnd(): self
     }
 
     /**
-     * @return $this
+     * Align columns to the start of the container.
+     *
+     * This method sets the vertical alignment of the columns to the start,
+     * positioning all columns at the top of the container.
+     *
+     * @return $this Returns the current instance for method chaining.
      */
     public function alignStart(): self
     {