glib-web 4.39.2 → 4.40.0

data/app/helpers/glib/json_ui/view_builder/fields.rb

@@ -1,18 +1,61 @@
 class Glib::JsonUi::ViewBuilder
+  # Field components for JSON UI forms.
+  #
+  # This module contains all field types that can be used in forms, providing a consistent
+  # interface between Ruby backend and Vue.js frontend components.
+  #
+  # All fields automatically integrate with form validation, I18n labels, and model binding.
   module Fields
 
+    # Base class for all field components.
+    #
+    # AbstractField provides common functionality shared by all form fields including:
+    # - Automatic label and placeholder resolution from I18n
+    # - Model property binding with `prop` parameter
+    # - Client-side validation with automatic error messages
+    # - Form integration and dirty checking
+    # - Change event handlers
+    #
+    # @abstract Subclass and override {#determine_value} to customize value extraction from models
+    # @see Panels::Form Form panel that contains field components
     class AbstractField < View
       include Rails.application.routes.url_helpers
 
+      # Makes field read-only (user can see but not edit the value).
       bool :readOnly
+
+      # Disables field entirely (grayed out, not submitted with form).
       bool :disabled
+
+      # Shows a clear button to reset the field value to empty.
       bool :clearable
+
+      # Action triggered when field value changes.
+      # @example
+      #   onChange: ->(action) do
+      #     action.http_get url: preview_path, silent: true
+      #   end
       action :onChange
+
+      # Action triggered when field value changes, with page reload.
+      # Use this when the change requires server-side processing and page refresh.
       action :onChangeAndLoad
+
+      # Custom parameter name for form submission data.
+      # Overrides the default parameter name derived from the model and property.
       string :paramNameForFormData
+
+      # Custom parameter name for field identification.
+      # Used to identify this field in form validation and error messages.
       string :paramNameForFieldName
+
+      # Makes field corners rounded (visual styling).
       bool :rounded
-      string :autocomplete # https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+
+      # HTML autocomplete attribute value.
+      # Controls browser autocomplete behavior.
+      # @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete MDN autocomplete reference
+      string :autocomplete
 
       def default_url_options
         { only_path: true }
@@ -31,7 +74,7 @@ class Glib::JsonUi::ViewBuilder
 
         # Validate that all keys are supported validation types
         supported_validations = %i[presence required absence acceptance numericality format inclusion exclusion length]
-        invalid_keys = validation.keys - supported_validations
+        invalid_keys = validation.keys.map(&:to_sym) - supported_validations
         if invalid_keys.any?
           raise ArgumentError, "Unsupported validation type(s): #{invalid_keys.join(', ')}. Supported types: #{supported_validations.join(', ')}"
         end
@@ -140,36 +183,141 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
+    # Basic text input field for single-line text entry.
+    #
+    # The most common field type, supporting various customizations like
+    # icons, prefix/suffix text, character limits, and typing event handlers.
+    #
+    # @example Basic text field
+    #   form.fields_text name: 'user[name]', width: 'matchParent', label: 'Name'
+    #
+    # @example Text field with model property binding
+    #   form.fields_text \
+    #     prop: :name,
+    #     name: 'user[name]',
+    #     width: 'matchParent',
+    #     label: 'Name'
+    #
+    # @see app/views/json_ui/garage/forms/basic.json.jbuilder Garage example
     class Text < AbstractField
+      # Maximum number of characters allowed.
       int :maxLength
+
+      # Icon displayed on the left side of the input.
+      # @example leftIcon: { name: 'account', color: 'primary' }
       icon :leftIcon
+
+      # Icon displayed on the right side of the input.
       icon :rightIcon
+
+      # Static text displayed on the left side of the input.
+      # @example leftText: '$' for currency inputs
       string :leftText
+
+      # Static text displayed on the right side of the input.
+      # @example rightText: 'USD' for currency inputs
       string :rightText
+
+      # Action triggered when user starts typing.
       action :onTypeStart
+
+      # Action triggered when user stops typing (debounced).
+      # Useful for search-as-you-type functionality.
       action :onTypeEnd
+
+      # Shows a clear button to reset the field value.
       bool :clearable
     end
 
+    # Numeric input field with number-specific validation.
+    #
+    # Extends Text field with min/max constraints and decimal precision support.
+    # Automatically validates that input is a valid number.
+    #
+    # @example Numeric field with validation
+    #   form.fields_number \
+    #     prop: :age,
+    #     name: 'user[age]',
+    #     width: 'matchParent',
+    #     label: 'Age',
+    #     clearable: true
+    #
+    # @see app/views/json_ui/garage/forms/text_validation.json.jbuilder Garage example
     class Number < Text
+      # Minimum numeric value allowed.
       int :min
+
+      # Maximum numeric value allowed.
       int :max
+
+      # Number of decimal places to allow.
+      # @example precision: 2 for currency (e.g., 10.99)
       int :precision
     end
 
+    # Email input field with email format validation.
+    #
+    # Uses browser's built-in email validation and provides
+    # appropriate keyboard on mobile devices.
+    #
+    # @example Email field with clearable button
+    #   form.fields_email \
+    #     name: 'user[email]',
+    #     width: 'matchParent',
+    #     label: 'Email',
+    #     clearable: true
+    #
+    # @see app/views/json_ui/garage/forms/text_validation.json.jbuilder Garage example
     class Email < Text
     end
 
+    # URL input field with URL format validation.
+    #
+    # Validates that input is a properly formatted URL and provides
+    # appropriate keyboard on mobile devices.
+    #
+    # @example URL field
+    #   form.fields_url \
+    #     name: 'user[url]',
+    #     width: 'matchParent',
+    #     label: 'URL',
+    #     clearable: true
+    #
+    # @see app/views/json_ui/garage/forms/text_validation.json.jbuilder Garage example
     class Url < Text
     end
 
+    # Password input field with masked input.
+    #
+    # Masks the input text and provides a toggle button to show/hide the password.
+    # Never pre-fills password values for security.
+    #
+    # @example Password field with icon and hint
+    #   form.fields_password \
+    #     name: 'user[password]',
+    #     width: 'matchParent',
+    #     label: 'Password',
+    #     hint: 'Should contain at least 6 characters',
+    #     leftIcon: 'lock',
+    #     clearable: true
+    #
+    # @see app/views/json_ui/garage/forms/text_validation.json.jbuilder Garage example
     class Password < Text
     end
 
+    # Hidden input field not visible to users.
+    #
+    # Submitted with the form but not displayed. Useful for passing
+    # data like IDs, tokens, or state that users shouldn't see or modify.
+    #
+    # @example Hidden field
+    #   form.fields_hidden name: 'mode', value: 'dialog'
+    #
+    # @see app/views/json_ui/garage/forms/_basic_content.json.jbuilder Garage example
     class Hidden < Text
 
       def created
-        # no need to auto translate this
+        # Hidden fields don't need labels or placeholders
         @label = ''
         @placeholder = ''
 
@@ -177,40 +325,159 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
+    # Timer/stopwatch field for time tracking.
+    #
+    # Can count up (stopwatch mode) or down (countdown timer mode).
+    # Supports min/max time constraints.
+    #
+    # @example Countdown timer (backward)
+    #   form.fields_timer \
+    #     width: 160,
+    #     styleClasses: ['outlined'],
+    #     label: 'Timer',
+    #     name: 'user[timer]',
+    #     value: 60,
+    #     min: 30
+    #
+    # @example Stopwatch (forward)
+    #   form.fields_timer \
+    #     width: 160,
+    #     styleClasses: ['outlined'],
+    #     label: 'Stop Watch',
+    #     name: 'user[stop_watch]',
+    #     value: 10,
+    #     max: 20,
+    #     forward: true
+    #
+    # @see app/views/json_ui/garage/forms/timers.json.jbuilder Garage example
     class Timer < Text
-      # hash :actionCable
+      # hash :actionCable  # Future: ActionCable integration for real-time updates
+
+      # Minimum timer value (in seconds).
       int :min
+
+      # Maximum timer value (in seconds).
       int :max
+
+      # Direction of counting.
+      # - true: Count up (stopwatch mode)
+      # - false: Count down (timer mode)
       bool :forward
     end
 
-    # Benefits of using `fields/submit` over `button`
-    # - On the web, it translates to input[type=submit] which provides builtin functionality such as
-    #   submitting upon pressing enter on a field and remembering values for autofill.
-    # - We can attach name-value param to it. See https://www.w3schools.com/tags/att_button_value.asp
-    # - It has a default onClick so no need to specify `onClick: ->(action) { action.forms_submit }`
+    # Submit button field for form submission.
+    #
+    # Benefits of using `fields/submit` over regular `button`:
+    # - On the web, translates to input[type=submit] which provides built-in browser
+    #   functionality like submitting on Enter key and remembering values for autofill
+    # - Can attach name-value params (unlike regular buttons)
+    # - Has default onClick behavior so no need to manually specify form submission
+    #
+    # @example Basic submit button
+    #   form.fields_submit text: 'Submit'
+    #
+    # @see app/views/json_ui/garage/forms/basic.json.jbuilder Garage example
+    # @see https://www.w3schools.com/tags/att_button_value.asp HTML button value attribute
     class Submit < AbstractField
+      # Button text to display.
       string :text
+
+      # Button color theme.
+      # @example color: 'primary', 'secondary', 'error'
       color :color
+
+      # Icon to display in the button.
       icon :icon
-      # This will not work if the form contains multiple fields with the same name,
-      # even if only one field is showing at any one time"
+
+      # Disables button when form has validation errors.
+      # Note: This will not work correctly if the form contains multiple fields
+      # with the same name, even if only one field is visible at a time.
       bool :disableIfFormInvalid
     end
 
+    # Group of checkbox fields managed as a collection.
+    #
+    # Manages multiple checkboxes as a single form field, useful for
+    # multi-select scenarios where values are submitted as an array.
+    #
+    # @example Basic checkbox group
+    #   form.fields_checkGroup \
+    #     name: 'user[skills][]',
+    #     uncheckValue: 1,
+    #     childViews: ->(group) do
+    #       group.fields_check checkValue: 2, label: 'Game Development (readOnly)', readOnly: true
+    #       group.fields_check checkValue: 3, label: 'Web Development'
+    #       group.fields_check checkValue: 4, label: 'Mobile Development'
+    #     end
+    #
+    # @example Checkbox group with "none of above" option
+    #   form.fields_checkGroup \
+    #     valueForDisableAll: 'none_of_above',
+    #     name: 'user[favorite_fruits][]',
+    #     value: 'grape',
+    #     uncheckValue: 1,
+    #     childViews: ->(group) do
+    #       group.fields_check label: 'Grape', checkValue: 'grape'
+    #       group.fields_check label: 'Banana', checkValue: 'banana'
+    #       group.fields_check label: 'Durian', checkValue: 'durian'
+    #       group.fields_check label: 'I dont like fruits', checkValue: 'none_of_above'
+    #     end
+    #
+    # @see app/views/json_ui/garage/forms/checkboxes.json.jbuilder Garage example
     class CheckGroup < AbstractField
+      # Child checkbox field components.
       views :childViews
+
+      # Value to use when a checkbox is unchecked.
+      # @example uncheckValue: '0'
       string :uncheckValue
+
+      # Special value that, when checked, disables all other checkboxes.
+      # Useful for "None" or "Disable All" options.
       string :valueForDisableAll
     end
 
+    # Individual checkbox field.
+    #
+    # Can be used standalone or within a CheckGroup. Supports custom icons,
+    # images, and indeterminate state for partial selections.
+    #
+    # @example Single checkbox with default value
+    #   form.fields_check \
+    #     name: 'user[age_range]',
+    #     value: '16+',
+    #     checkValue: '16+',
+    #     uncheckValue: '0-16',
+    #     label: 'I am over 16 (has default value)'
+    #
+    # @example Standalone checkboxes without group
+    #   form.fields_check name: 'user[choice][]', label: 'Choice 1', checkValue: 'choice_1'
+    #   form.fields_check name: 'user[choice][]', label: 'Choice 2', checkValue: 'choice_2'
+    #
+    # @see app/views/json_ui/garage/forms/checkboxes.json.jbuilder Garage example
+    # @see app/views/json_ui/garage/forms/pickers.json.jbuilder Garage example for single checkbox
     class Check < Text
+      # Value when checkbox is unchecked.
       any :uncheckValue
+
+      # Value when checkbox is checked.
       any :checkValue
+
+      # Icon to display when checked.
       string :onIcon
+
+      # Icon to display when unchecked.
       string :offIcon
+
+      # Label to display when checked (replaces default label).
       string :onLabel
+
+      # Image to display instead of standard checkbox.
+      # @example image: { url: '/checkmark.png', template: 'image', width: 24, height: 24 }
       hash :image, required: [:url, :template], optional: [:width, :height]
+
+      # Shows indeterminate state (partially checked).
+      # Useful for "select all" checkboxes when some but not all children are selected.
       bool :indeterminate
 
       def value(value)
@@ -218,18 +485,79 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
-    # This doesn't use camel case because some terms have become single words (e.g. snackbar)
+    # Multi-line text input field.
+    #
+    # For longer text entries that need multiple lines, such as comments,
+    # descriptions, or notes.
+    #
+    # @example Textarea with character limit
+    #   form.fields_textarea \
+    #     prop: :words,
+    #     name: 'user[words]',
+    #     width: 'matchParent',
+    #     label: 'Textarea with maxLength',
+    #     maxLength: 1000,
+    #     clearable: true
+    #
+    # @see app/views/json_ui/garage/forms/text_validation.json.jbuilder Garage example
     class Textarea < Text
     end
 
+    # Rich text editor field with WYSIWYG editing.
+    #
+    # Provides a full-featured text editor with formatting options, image uploads,
+    # and @mention support. Can output HTML or Markdown.
+    #
+    # @example Rich text editor with image upload and mentions
+    #   avatar = 'https://example.com/avatar.jpg'
+    #   mention_list = [
+    #     { id: 'johndoe', value: 'johndoe', text: 'John Doe', avatar: avatar, group: 'Programmer' },
+    #     { id: 'budi', value: 'budi', text: 'Budi', avatar: avatar, group: 'Programmer' }
+    #   ]
+    #   form.fields_richText \
+    #     width: 'matchParent',
+    #     produce: :markdown,
+    #     label: 'Content',
+    #     name: 'user[message]',
+    #     value: initial_message,
+    #     mentionList: mention_list,
+    #     imageUploader: {
+    #       name: 'user[images_attributes][]',
+    #       accepts: { fileType: ['image', 'csv', 'xlsx', 'pptx', 'docx'], maxFileSize: 5000 },
+    #       directUploadUrl: glib_direct_uploads_url,
+    #       blobUrlGenerator: glib_blob_url_generators_url
+    #     },
+    #     debug: true
+    #
+    # @see app/views/json_ui/garage/forms/rich_text.json.jbuilder Garage example
     class RichText < Text
+      # Pre-loaded images already in the content.
       array :images
+
+      # Configuration for image upload functionality.
+      # @example
+      #   imageUploader: {
+      #     name: 'post[images][]',
+      #     directUploadUrl: rails_direct_uploads_path,
+      #     accepts: 'image/png,image/jpeg'
+      #   }
       hash :imageUploader, required: [:name], optional: [:accepts, :directUploadUrl, :blobUrlGenerator]
-      # `html` or `markdown`
-      string :produce
-      string :accept
+
+      # Output format for the editor content.
+      enum :produce, options: [:html, :markdown]
+
+      # Input format the editor should accept.
+      enum :accept, options: [:html, :markdown]
+
+      # Cache key for editor state persistence.
+      # Helps restore editor content if the page is reloaded.
       string :cacheKey
+
+      # List of users/entities that can be mentioned with @ symbol.
+      # @example mentionList: [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
       array :mentionList
+
+      # Enables debug mode with additional logging.
       bool :debug
     end
 
@@ -426,12 +754,14 @@ class Glib::JsonUi::ViewBuilder
           key = "glib.multi_upload.responseMessages.#{status}"
           @responseMessages[status] = I18n.t(key) if I18n.exists?(key)
         end
-        json.responseMessages (@responseMessages || {}).reverse_merge({
-          '200' => 'Completed',
-          '403' => 'Forbidden',
-          '401' => 'Session expired',
-          'else' => 'Failed'
-        })
+        json.responseMessages(
+          (@responseMessages || {}).reverse_merge(
+            '200' => 'Completed',
+            '403' => 'Forbidden',
+            '401' => 'Session expired',
+            'else' => 'Failed'
+          )
+        )
 
         json.placeholder @placeholder if @placeholder
         json.hint @hint if @hint
@@ -478,12 +808,14 @@ class Glib::JsonUi::ViewBuilder
             @multi_progress['responseMessages'][status] = I18n.t(key) if I18n.exists?(key)
           end
 
-          json.responseMessages (@multi_progress['responseMessages'] || {}).reverse_merge({
-            '200' => 'Completed',
-            '403' => 'Forbidden',
-            '401' => 'Session expired',
-            'else' => 'Failed'
-          })
+          json.responseMessages(
+            (@multi_progress['responseMessages'] || {}).reverse_merge(
+              '200' => 'Completed',
+              '403' => 'Forbidden',
+              '401' => 'Session expired',
+              'else' => 'Failed'
+            )
+          )
 
           json.placeholder @placeholder if @placeholder
           json.hint @hint if @hint
@@ -519,7 +851,10 @@ class Glib::JsonUi::ViewBuilder
     class Date < AbstractField
       date :min
       date :max
-      string :type
+      # Date picker type.
+      # - :month - Month picker (YYYY-MM format)
+      # - nil/omitted - Standard date picker (YYYY-MM-DD format)
+      enum :type, options: [:month]
       bool :clearable
       bool :buttonTemplate # TODO: Remove
       hash :template, required: [:type]
@@ -543,45 +878,215 @@ class Glib::JsonUi::ViewBuilder
       hash :template, required: [:type]
     end
 
+    # Location/address field with Google Places autocomplete integration.
+    #
+    # Integrates with Google Places API to provide address autocomplete
+    # and geocoding. Can optionally store latitude, longitude, and zoom level
+    # in separate fields.
+    #
+    # @example Location field with coordinates and country restriction
+    #   form.fields_location \
+    #     name: 'user[address]',
+    #     width: 'matchParent',
+    #     label: 'Type an address',
+    #     value: 'Sydney Harbour Bridge',
+    #     autocompleteOptions: { componentRestrictions: { country: 'au' }, types: ['(cities)'] },
+    #     latitudeField: { view: 'fields/text', name: 'user[latitude]', label: 'Lat', value: -33.8523063, readOnly: true },
+    #     longitudeField: { view: 'fields/text', name: 'user[longitude]', label: 'Long', value: 151.21078710000006, readOnly: true },
+    #     zoomField: { view: 'fields/text', name: 'user[zoom]', label: 'Zoom' }
+    #
+    # @see app/views/json_ui/garage/forms/pickers.json.jbuilder Garage example
+    # @see https://developers.google.com/maps/documentation/javascript/reference/places-widget#AutocompleteOptions Google Places API
     class Location < AbstractField
+      # Hidden field configuration for storing latitude value.
+      # @example latitudeField: { name: 'venue[latitude]' }
       hash :latitudeField
+
+      # Hidden field configuration for storing longitude value.
+      # @example longitudeField: { name: 'venue[longitude]' }
       hash :longitudeField
+
+      # Hidden field configuration for storing map zoom level.
       hash :zoomField
-      # https://developers.google.com/maps/documentation/javascript/reference/places-widget#AutocompleteOptions
+
+      # Google Places Autocomplete options for customizing search behavior.
+      # @example
+      #   autocompleteOptions: {
+      #     componentRestrictions: { country: ['us', 'ca'] },
+      #     types: ['geocode'],
+      #     fields: ['formatted_address', 'geometry']
+      #   }
+      # @see https://developers.google.com/maps/documentation/javascript/reference/places-widget#AutocompleteOptions
       hash :autocompleteOptions, optional: [:bounds, :componentRestrictions, :fields, :strictBounds, :types]
     end
 
+    # Stripe payment token field for secure card tokenization.
+    #
+    # Generates Stripe tokens from credit card information without your server
+    # ever handling raw card details. Compliant with PCI DSS requirements.
+    #
+    # @example Stripe credit card token field
+    #   form.fields_stripeToken \
+    #     name: 'user[stripe_token]',
+    #     width: 'matchParent',
+    #     publicKey: 'pk_test_TYooMQauvdEDq54NiTphI7jx'
+    #
+    # @see app/views/json_ui/garage/forms/payments.json.jbuilder Garage example
+    # @see https://stripe.com/docs/stripe-js Stripe.js documentation
     class StripeToken < AbstractField
+      # Your Stripe publishable key.
+      # Never use your secret key in client-side code.
       string :publicKey
     end
 
+    # Stripe external account field for Connect platform.
+    #
+    # Allows users to connect their bank accounts to receive payouts via Stripe Connect.
+    # Handles bank account details securely without storing sensitive information.
+    #
+    # @example Stripe bank account field
+    #   form.fields_stripeExternalAccount \
+    #     name: 'user[stripe_external_account]',
+    #     width: 'matchParent',
+    #     publicKey: 'pk_test_TYooMQauvdEDq54NiTphI7jx',
+    #     accountHolderName: 'John Doe',
+    #     accountHolderType: 'individual',
+    #     country: 'AU',
+    #     currency: 'AUD'
+    #
+    # @see app/views/json_ui/garage/forms/payments.json.jbuilder Garage example
+    # @see https://stripe.com/docs/connect/payouts Stripe Connect documentation
     class StripeExternalAccount < AbstractField
+      # Your Stripe publishable key.
       string :publicKey
+
+      # Name of the bank account holder.
       string :accountHolderName
-      string :accountHolderType
+
+      # Type of account holder.
+      enum :accountHolderType, options: [:individual, :company]
+
+      # Two-letter country code (ISO 3166-1 alpha-2).
+      # @example country: 'US', 'CA', 'GB'
       string :country
+
+      # Three-letter currency code (ISO 4217).
+      # @example currency: 'usd', 'eur', 'gbp'
       string :currency
     end
 
+    # International phone number input field.
+    #
+    # Provides phone number input with country code selector and automatic
+    # formatting. Includes validation for phone number formats.
+    #
+    # @example Basic phone field with auto-detect
+    #   form.fields_phone \
+    #     name: 'user[phone1]',
+    #     width: 'matchParent',
+    #     label: 'Phone field',
+    #     clearable: true
+    #
+    # @example Phone field with default country (no auto-detect)
+    #   form.fields_phone \
+    #     name: 'user[phone2]',
+    #     width: 'matchParent',
+    #     label: 'Phone field with Australia as the default country',
+    #     disableAutoDetect: true,
+    #     defaultCountry: 'AU'
+    #
+    # @see app/views/json_ui/garage/forms/text_validation.json.jbuilder Garage example
     class Phone < AbstractField
+      # Default country code to preselect.
+      # @example defaultCountry: 'US', 'GB', 'AU'
       string :defaultCountry
+
+      # Disables automatic country detection based on user's location.
       bool :disableAutoDetect
+
+      # Shows a clear button to reset the field value.
       bool :clearable
     end
 
+    # Credit card input field with secure tokenization.
+    #
+    # Integrates with payment processors to securely collect credit card details.
+    # Handles card number, expiry, and CVV without exposing sensitive data to your server.
+    #
+    # @example Credit card field
+    #   form.fields_credit_card \
+    #     prop: :payment_token,
+    #     publicKey: ENV['PAYMENT_PROCESSOR_PUBLIC_KEY']
     class CreditCard < AbstractField
+      # Payment processor's public/publishable key.
+      # Used for client-side tokenization.
       string :publicKey
     end
 
+    # One-Time Password (OTP) input field.
+    #
+    # Provides a specialized input for entering verification codes with
+    # separate boxes for each digit. Commonly used for 2FA or phone verification.
+    #
+    # @example 7-character OTP field (text type)
+    #   form.fields_otp \
+    #     name: 'user[otp_summary1]',
+    #     length: 7,
+    #     type: 'text'
+    #
+    # @example 3-digit OTP field (number type)
+    #   form.fields_otp \
+    #     name: 'user[otp_summary2]',
+    #     length: 3,
+    #     type: 'number'
+    #
+    # @see app/views/json_ui/garage/forms/otp_field.json.jbuilder Garage example
     class Otp < AbstractField
-      int     :length
-      string :type
+      # Number of OTP digits/characters.
+      # @example length: 4, 6, or 8
+      int :length
+
+      # Input type for each character box.
+      enum :type, options: [:text, :number]
     end
 
+    # Star rating input field.
+    #
+    # Provides an interactive star rating interface for collecting user ratings.
+    # Supports full and half-star increments with customizable appearance.
+    #
+    # @example Rating with full increments
+    #   form.fields_rating \
+    #     name: 'user[rating_summary1]',
+    #     value: 1,
+    #     color: 'primary'
+    #
+    # @example Rating with half-star increments
+    #   form.fields_rating \
+    #     name: 'user[rating_summary2]',
+    #     value: 1.5,
+    #     halfIncrements: true,
+    #     color: 'secondary'
+    #
+    # @example Rating with custom size
+    #   form.fields_rating \
+    #     name: 'user[rating_summary3]',
+    #     value: 2,
+    #     color: 'ternary',
+    #     size: 35
+    #
+    # @see app/views/json_ui/garage/forms/ratings.json.jbuilder Garage example
     class Rating < AbstractField
-      bool    :halfIncrements
-      string  :color
-      int     :size
+      # Allows selecting half-star values (e.g., 3.5 stars).
+      bool :halfIncrements
+
+      # Color theme for the stars.
+      # @example color: 'amber', 'yellow', 'orange'
+      string :color
+
+      # Size of each star in pixels.
+      # @example size: 24, 32, 48
+      int :size
     end
   end
 end