From d05caca6aea2096971d191c994787cef103f695e Mon Sep 17 00:00:00 2001
From: Tommmaso Menga <tommaso.menga-94@hotmail.it>
Date: Wed, 23 Oct 2024 10:23:36 +0200
Subject: [PATCH] fix(sbb-radio-button): pr feedbacks

---
 .../form-associated-radio-button-mixin.ts     | 24 +++++++++++++------
 .../common/radio-button-common.ts             |  4 ++--
 .../radio-button/radio-button-panel/readme.md |  6 ++---
 .../radio-button/radio-button/readme.md       |  6 ++---
 4 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/src/elements/core/mixins/form-associated-radio-button-mixin.ts b/src/elements/core/mixins/form-associated-radio-button-mixin.ts
index b75acfa8f8..1990137507 100644
--- a/src/elements/core/mixins/form-associated-radio-button-mixin.ts
+++ b/src/elements/core/mixins/form-associated-radio-button-mixin.ts
@@ -38,7 +38,8 @@ export declare class SbbFormAssociatedRadioButtonMixinType
 }
 
 /**
- * TODO add docs (maybe move to new file)
+ * A static registry that holds a collection of `radio-buttons`, grouped by `name`.
+ * It is mainly used to support the standalone groups of radios.
  * @internal
  */
 export class RadioButtonRegistry {
@@ -46,6 +47,9 @@ export class RadioButtonRegistry {
 
   private constructor() {}
 
+  /**
+   * Adds @radio to the @groupName group. Checks for duplicates
+   */
   public static addRadioToGroup(
     radio: SbbFormAssociatedRadioButtonMixinType,
     groupName: string,
@@ -60,6 +64,9 @@ export class RadioButtonRegistry {
     this._registry[groupName].push(radio);
   }
 
+  /**
+   * Removes @radio from the @groupName group.
+   */
   public static removeRadioFromGroup(
     radio: SbbFormAssociatedRadioButtonMixinType,
     groupName: string,
@@ -75,6 +82,9 @@ export class RadioButtonRegistry {
     }
   }
 
+  /**
+   * Return an array of radios that belong to @groupName
+   */
   public static getRadios(groupName: string): SbbFormAssociatedRadioButtonMixinType[] {
     return this._registry[groupName] ?? [];
   }
@@ -180,7 +190,7 @@ export const SbbFormAssociatedRadioButtonMixin = <T extends Constructor<LitEleme
 
     /**
      * Called on `value` change
-     * If I'm checked, update the value. Otherwise, do nothing.
+     * If 'checked', update the value. Otherwise, do nothing.
      */
     protected override updateFormValue(): void {
       if (this.checked) {
@@ -190,7 +200,7 @@ export const SbbFormAssociatedRadioButtonMixin = <T extends Constructor<LitEleme
 
     /**
      * Called on `checked` change
-     * If I'm checked, set the value. Otherwise, reset it.
+     * If 'checked', update the value. Otherwise, reset it.
      */
     protected updateFormValueOnCheckedChange(): void {
       this.internals.setFormValue(this.checked ? this.value : null);
@@ -198,14 +208,14 @@ export const SbbFormAssociatedRadioButtonMixin = <T extends Constructor<LitEleme
 
     /**
      * Only a single radio should be focusable in the group. Defined as:
-     * - the checked radios;
+     * - the checked radio;
      * - the first non-disabled radio in DOM order;
      */
     protected updateFocusableRadios(): void {
       if (!this._didLoad) {
         return;
       }
-      const radios = this._orderedGrouperRadios();
+      const radios = this._orderedGroupedRadios();
       const checkedIndex = radios.findIndex((r) => r.checked && !r.disabled && !r.formDisabled);
       const focusableIndex =
         checkedIndex !== -1
@@ -275,7 +285,7 @@ export const SbbFormAssociatedRadioButtonMixin = <T extends Constructor<LitEleme
     /**
      * Return the grouped radios in DOM order
      */
-    private _orderedGrouperRadios(groupName = this.name): SbbFormAssociatedRadioButtonElement[] {
+    private _orderedGroupedRadios(groupName = this.name): SbbFormAssociatedRadioButtonElement[] {
       return Array.from(
         (this.form ?? document).querySelectorAll<SbbFormAssociatedRadioButtonElement>(
           `:is(sbb-radio-button, sbb-radio-button-panel)[name="${groupName}"]`,
@@ -289,7 +299,7 @@ export const SbbFormAssociatedRadioButtonMixin = <T extends Constructor<LitEleme
       }
       evt.preventDefault();
 
-      const enabledRadios = this._orderedGrouperRadios().filter(
+      const enabledRadios = this._orderedGroupedRadios().filter(
         (r) => !r.disabled && !r.formDisabled,
       );
       const current: number = enabledRadios.indexOf(this);
diff --git a/src/elements/radio-button/common/radio-button-common.ts b/src/elements/radio-button/common/radio-button-common.ts
index 8fa320a4ef..5065e03e2f 100644
--- a/src/elements/radio-button/common/radio-button-common.ts
+++ b/src/elements/radio-button/common/radio-button-common.ts
@@ -88,8 +88,8 @@ export const SbbRadioButtonCommonElementMixin = <T extends Constructor<LitElemen
     }
 
     /**
-     * Set the radio-button as 'checked'. If 'allowEmptySelection', toggle the checked property.
-     * Emits events
+     * Set the radio-button as 'checked'; if 'allowEmptySelection', toggle the checked property.
+     * In both cases it emits the change events.
      */
     public select(): void {
       if (this.disabled || this.formDisabled) {
diff --git a/src/elements/radio-button/radio-button-panel/readme.md b/src/elements/radio-button/radio-button-panel/readme.md
index 0d0802d487..035ddbe287 100644
--- a/src/elements/radio-button/radio-button-panel/readme.md
+++ b/src/elements/radio-button/radio-button-panel/readme.md
@@ -84,9 +84,9 @@ The component's label can be displayed in bold using the `sbb-text--bold` class
 
 ## Methods
 
-| Name     | Privacy | Description                                                                                            | Parameters | Return | Inherited From                   |
-| -------- | ------- | ------------------------------------------------------------------------------------------------------ | ---------- | ------ | -------------------------------- |
-| `select` | public  | Set the radio-button as 'checked'. If 'allowEmptySelection', toggle the checked property. Emits events |            | `void` | SbbRadioButtonCommonElementMixin |
+| Name     | Privacy | Description                                                                                                                         | Parameters | Return | Inherited From                   |
+| -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | -------------------------------- |
+| `select` | public  | Set the radio-button as 'checked'; if 'allowEmptySelection', toggle the checked property. In both cases it emits the change events. |            | `void` | SbbRadioButtonCommonElementMixin |
 
 ## Events
 
diff --git a/src/elements/radio-button/radio-button/readme.md b/src/elements/radio-button/radio-button/readme.md
index c9f19e0360..771e0fe865 100644
--- a/src/elements/radio-button/radio-button/readme.md
+++ b/src/elements/radio-button/radio-button/readme.md
@@ -75,9 +75,9 @@ The component's label can be displayed in bold using the `sbb-text--bold` class
 
 ## Methods
 
-| Name     | Privacy | Description                                                                                            | Parameters | Return | Inherited From                   |
-| -------- | ------- | ------------------------------------------------------------------------------------------------------ | ---------- | ------ | -------------------------------- |
-| `select` | public  | Set the radio-button as 'checked'. If 'allowEmptySelection', toggle the checked property. Emits events |            | `void` | SbbRadioButtonCommonElementMixin |
+| Name     | Privacy | Description                                                                                                                         | Parameters | Return | Inherited From                   |
+| -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | -------------------------------- |
+| `select` | public  | Set the radio-button as 'checked'; if 'allowEmptySelection', toggle the checked property. In both cases it emits the change events. |            | `void` | SbbRadioButtonCommonElementMixin |
 
 ## Events