refactor(docs): improve pf-helper-text code, translate comments, align docs with pf-icon

Author: dali327519294

elements/pf-helper-text/README.md

@@ -1,11 +1,35 @@
-# Helper Text
-Add a description of the component here.
+# `<pf-helper-text>`
 
-## Usage
-Describe how best to use this web component along with best practices.
+The **pf-helper-text** component provides contextual helper messages that indicate status, such as success, warning, error, or informational messages.  
+It can include icons and supports custom content via slots.
 
+---
+
+##  Usage
+
+Import the component before using it:
+
+```js
+import '@patternfly/elements/pf-helper-text/pf-helper-text.js';
+import '@patternfly/elements/pf-icon/pf-icon.js';
+
+import '@patternfly/elements/pf-helper-text/pf-helper-text.js';
+import '@patternfly/elements/pf-icon/pf-icon.js';
 ```html
-<pf-helper-text>
+<pf-helper-text status="warning">
+  This is a warning helper text
+</pf-helper-text>
 
+<pf-helper-text status="error" icon="exclamation-triangle" icon-set="fas">
+  This is an error helper text with icon
 </pf-helper-text>
+
+<pf-helper-text status="success">
+  <svg slot="icon" width="16" height="16" viewBox="0 0 16 16" fill="green" xmlns="http://www.w3.org/2000/svg">
+    <path d="M6 10.8L3.2 8 2 9.2l4 4 8-8-1.2-1.2L6 10.8z"/>
+  </svg>
+  This is a success helper text with slotted icon
+</pf-helper-text>
+
+
 ```

elements/pf-helper-text/pf-helper-text.ts

@@ -7,81 +7,108 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import styles from './pf-helper-text.css';
 
 /**
- * Helper Text Statuses
+ * Status types for helper text.
+ * Determines which default icon to show if no custom icon is provided.
  */
 export type HelperTextStatus = 'default' | 'success' | 'warning' | 'error' | 'indeterminate';
 
 /**
  * Helper Text
- * @slot icon - Custom icon to override default
- * @slot - Place element content here
+ *
+ * Provides contextual feedback for form fields or UI elements.
+ * Allows showing default icons based on status or custom icons via properties or slotted content.
+ *
+ * Slots:
+ * - `icon`: optional slot to override the default icon
+ * - default slot: place any text/content
+ *
+ * Properties:
+ * - `status`: sets the helper text status and chooses a default icon
+ * - `icon`: custom icon name (overrides default)
+ * - `iconSet`: icon set to use when `icon` is specified
+ *
+ * Events:
+ * - `icon-load`: fired when the icon successfully loads
+ * - `icon-error`: fired if loading the icon fails, includes the error detail
  */
 @customElement('pf-helper-text')
 export class PfHelperText extends LitElement {
+  /** Static styles for the component */
   static readonly styles: CSSStyleSheet[] = [styles];
 
   /**
-   * Defines the helper text status and its corresponding icon.
-   * Options include 'default', 'success', 'warning', 'error', 'indeterminate'.
+   * The helper text status.
+   * Options: 'default' | 'success' | 'warning' | 'error' | 'indeterminate'
+   * Determines the default icon if no custom icon is provided.
    */
   @property({ attribute: 'status' })
   status: HelperTextStatus = 'default';
 
   /**
-   * The icon name to use. Overrides the default icon for a given status.
+   * Name of a custom icon to display.
+   * Overrides the default icon associated with the status.
    * Requires pf-icon to be imported.
    */
   @property({ attribute: 'icon' })
   icon: string | undefined;
 
   /**
-   * The icon set to use, e.g., 'fas' for Font Awesome Solid.
-   * Required when using the 'icon' property.
+   * Icon set to use for the custom icon.
+   * Required when specifying the `icon` property.
    */
   @property({ attribute: 'icon-set' })
   iconSet: string | undefined;
 
   /**
-   * מחשב את האייקון שיוצג, בהתבסס על הסטטוס או המאפיין icon
+   * Computes the icon name to display.
+   * - Returns `icon` if defined
+   * - Otherwise maps `status` to a default icon
+   * - Returns undefined if no icon should be shown (status 'default')
    */
   private get _iconName(): string | undefined {
-    // אם המשתמש הגדיר אייקון ספציפי, השתמש בו
+    // Use custom icon if provided
     if (this.icon) {
       return this.icon;
     }
 
-    // אם לא הוגדר אייקון ספציפי, החזר אייקון ברירת מחדל לפי הסטטוס
+    // Map status to default icons
     switch (this.status) {
-      case 'success':
-        return 'circle-check';
-      case 'warning':
-        return 'exclamation-triangle';
-      case 'error':
-        return 'exclamation-circle';
-      case 'indeterminate':
-        return 'minus-circle';
-      default:
-        return undefined; // במצב 'default' אין אייקון ברירת מחדל
+      case 'success': return 'circle-check';
+      case 'warning': return 'exclamation-triangle';
+      case 'error': return 'exclamation-circle';
+      case 'indeterminate': return 'minus-circle';
+      default: return undefined; // no icon for default status
     }
   }
 
-  // בקובץ pf-helper-text.ts
+  /**
+   * Render method for the helper text element.
+   * - Renders `<pf-icon>` if there is an icon
+   * - Supports lazy loading to optimize performance
+   * - Fires `icon-load` and `icon-error` events from pf-icon
+   * - Provides slots for custom icons and text content
+   */
   render(): TemplateResult<1> {
-    const iconName = this._iconName; // מקבל את שם האייקון או undefined
+    const iconName = this._iconName;
     const hasIcon = !!iconName;
 
     return html`
-      
+      <!-- Slot for user-defined icon. If none is provided, render pf-icon -->
       <slot name="icon">
-        
         ${hasIcon ?
           html`
-            <pf-icon icon="${iconName}"  set="${ifDefined(this.iconSet)}" ></pf-icon>
-        
+            <pf-icon
+              icon="${iconName}"             <!-- icon name from _iconName -->
+              set="${ifDefined(this.iconSet)}" <!-- optional icon set -->
+              loading="lazy"                 <!-- defer loading until needed -->
+              @load=${() => this.dispatchEvent(new CustomEvent('icon-load', { bubbles: true }))} 
+              @error=${(e: Event) => this.dispatchEvent(new CustomEvent('icon-error', { bubbles: true, detail: e }))}
+            ></pf-icon>
           `
           : ''}
       </slot>
-      
+
+      <!-- Default slot for helper text content -->
       <slot></slot>
     `;
   }