Adds character counter to TextArea and TextField components

.changeset/plenty-regions-warn.md

@@ -0,0 +1,5 @@
+---
+'@primer/view-components': minor
+---
+
+Adds character_limit option to TextArea and TextField components

app/components/primer/alpha/text_area.rb

@@ -18,6 +18,7 @@ class TextArea < Primer::Component
       # @!method initialize
       #
       # @macro form_full_width_arguments
+      # @macro form_input_character_limit_arguments
       # @macro form_input_arguments
     end
   end

app/components/primer/alpha/text_field.rb

@@ -19,6 +19,7 @@ class TextField < Primer::Component
       #
       # @macro form_size_arguments
       # @macro form_full_width_arguments
+      # @macro form_input_character_limit_arguments
       # @macro form_input_arguments
       #
       # @param placeholder [String] Placeholder text.

app/components/primer/primer.ts

@@ -22,6 +22,7 @@ import './beta/relative_time'
 import './alpha/tab_container'
 import '../../lib/primer/forms/primer_multi_input'
 import '../../lib/primer/forms/primer_text_field'
+import '../../lib/primer/forms/primer_text_area'
 import '../../lib/primer/forms/toggle_switch_input'
 import './alpha/action_menu/action_menu_element'
 import './alpha/select_panel_element'

app/forms/text_area_with_character_limit_form.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# :nodoc:
+class TextAreaWithCharacterLimitForm < ApplicationForm
+  form do |my_form|
+    my_form.text_area(
+      name: :bio,
+      label: "Bio",
+      caption: "Tell us about yourself",
+      character_limit: 100
+    )
+  end
+end

app/forms/text_field_with_character_limit_form.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# :nodoc:
+class TextFieldWithCharacterLimitForm < ApplicationForm
+  form do |my_form|
+    my_form.text_field(
+      name: :username,
+      label: "Username",
+      caption: "Choose a unique username",
+      character_limit: 20
+    )
+  end
+end

app/lib/primer/forms/caption.html.erb

@@ -1,10 +1,16 @@
-<% if @input.caption? && [email protected]? %>
-  <span class="FormControl-caption" id="<%= @input.caption_id %>"><%= @input.caption %></span>
-<% elsif caption_template? %>
-  <% caption_template = render_caption_template %>
-  <% unless caption_template.blank? %>
-    <span class="FormControl-caption" id="<%= @input.caption_id %>">
-      <%= caption_template %>
-    </span>
-  <% end %>
+<% if @input.character_limit? %>
+  <span class="sr-only" data-target="<%= @input.character_limit_target_prefix %>.characterLimitSrElement" aria-live="polite" aria-atomic="true"></span>
+  <span class="FormControl-caption" data-target="<%= @input.character_limit_target_prefix %>.characterLimitElement" data-max-length="<%= @input.character_limit %>" id="<%= @input.character_limit_id %>">
+    <span class="FormControl-caption-icon" hidden><%= render(Primer::Beta::Octicon.new(icon: :"alert-fill", size: :xsmall, aria: { hidden: true })) %></span>
+    <span class="FormControl-caption-text"><%= @input.character_limit %> <%= @input.character_limit == 1 ? 'character' : 'characters' %> remaining</span>
+  </span>
+<% end %>
+<% if @input.caption? || caption_template? %>
+  <span class="FormControl-caption" id="<%= @input.caption_id %>">
+    <% if @input.caption? && [email protected]? %>
+      <%= @input.caption %>
+    <% elsif caption_template? %>
+      <%= render_caption_template %>
+    <% end %>
+  </span>
 <% end %>

app/lib/primer/forms/character_counter.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared character counting functionality for text inputs with character limits.
+ * Handles real-time character count updates, validation, and aria-live announcements.
+ */
+export class CharacterCounter {
+  private SCREEN_READER_DELAY: number = 500
+  private announceTimeout: number | null = null
+  private isInitialLoad: boolean = true
+
+  constructor(
+    private inputElement: HTMLInputElement | HTMLTextAreaElement,
+    private characterLimitElement: HTMLElement,
+    private characterLimitSrElement: HTMLElement,
+  ) {}
+
+  /**
+   * Initialize character counting by setting up event listener and initial count
+   */
+  initialize(signal?: AbortSignal): void {
+    this.inputElement.addEventListener('input', () => this.updateCharacterCount(), signal ? {signal} : undefined)
+    this.updateCharacterCount()
+    this.isInitialLoad = false
+  }
+
+  /**
+   * Clean up any pending timeouts
+   */
+  cleanup(): void {
+    if (this.announceTimeout) {
+      clearTimeout(this.announceTimeout)
+    }
+  }
+
+  /**
+   * Pluralizes a word based on the count
+   */
+  private pluralize(count: number, string: string): string {
+    return count === 1 ? string : `${string}s`
+  }
+
+  /**
+   * Update the character count display and validation state
+   */
+  private updateCharacterCount(): void {
+    if (!this.characterLimitElement) return
+
+    const maxLengthAttr = this.characterLimitElement.getAttribute('data-max-length')
+    if (!maxLengthAttr) return
+
+    const maxLength = parseInt(maxLengthAttr, 10)
+    const currentLength = this.inputElement.value.length
+    const charactersRemaining = maxLength - currentLength
+    let message = ''
+
+    if (charactersRemaining >= 0) {
+      const characterText = this.pluralize(charactersRemaining, 'character')
+      message = `${charactersRemaining} ${characterText} remaining`
+      const textSpan = this.characterLimitElement.querySelector('.FormControl-caption-text')
+      if (textSpan) {
+        textSpan.textContent = message
+      }
+      this.clearError()
+    } else {
+      const charactersOver = -charactersRemaining
+      const characterText = this.pluralize(charactersOver, 'character')
+      message = `${charactersOver} ${characterText} over`
+      const textSpan = this.characterLimitElement.querySelector('.FormControl-caption-text')
+      if (textSpan) {
+        textSpan.textContent = message
+      }
+      this.setError()
+    }
+
+    // We don't want this announced on initial load
+    if (!this.isInitialLoad) {
+      this.announceToScreenReader(message)
+    }
+  }
+
+  /**
+   * Announce character count to screen readers with debouncing
+   */
+  private announceToScreenReader(message: string): void {
+    if (this.announceTimeout) {
+      clearTimeout(this.announceTimeout)
+    }
+
+    this.announceTimeout = window.setTimeout(() => {
+      if (this.characterLimitSrElement) {
+        this.characterLimitSrElement.textContent = message
+      }
+    }, this.SCREEN_READER_DELAY)
+  }
+
+  /**
+   * Set error when character limit is exceeded
+   */
+  private setError(): void {
+    this.inputElement.setAttribute('invalid', 'true')
+    this.inputElement.setAttribute('aria-invalid', 'true')
+    this.characterLimitElement.classList.add('fgColor-danger')
+
+    // Show danger icon
+    const icon = this.characterLimitElement.querySelector('.FormControl-caption-icon')
+    if (icon) {
+      icon.removeAttribute('hidden')
+    }
+  }
+
+  /**
+   * Clear error when back under character limit
+   */
+  private clearError(): void {
+    this.inputElement.removeAttribute('invalid')
+    this.inputElement.removeAttribute('aria-invalid')
+    this.characterLimitElement.classList.remove('fgColor-danger')
+
+    // Hide danger icon
+    const icon = this.characterLimitElement.querySelector('.FormControl-caption-icon')
+    if (icon) {
+      icon.setAttribute('hidden', '')
+    }
+  }
+}

app/lib/primer/forms/dsl/input.rb

@@ -33,6 +33,9 @@ class Input
         # @!macro [new] form_full_width_arguments
         #   @param full_width [Boolean] When set to `true`, the field will take up all the horizontal space allowed by its container. Defaults to `true`.
 
+        # @!macro [new] form_input_character_limit_arguments
+        #   @param character_limit [Number] Optional character limit for the input. If provided, a character counter will be displayed below the input.
+
         # @!macro [new] form_system_arguments
         #   @param system_arguments [Hash] A hash of attributes passed to the underlying Rails builder methods. These options may mean something special depending on the type of input, otherwise they are emitted as HTML attributes. See the [Rails documentation](https://guides.rubyonrails.org/form_helpers.html) for more information. In addition, the usual Primer utility arguments are accepted in system arguments. For example, passing `mt: 2` will add the `mt-2` class to the input. See the Primer system arguments docs for details.
 
@@ -112,6 +115,7 @@ def initialize(builder:, form:, **system_arguments)
 
           @ids = {}.tap do |id_map|
             id_map[:validation] = "validation-#{@base_id}" if supports_validation?
+            id_map[:character_limit_caption] = "character_limit-#{@base_id}" if character_limit?
             id_map[:caption] = "caption-#{@base_id}" if caption? || caption_template?
           end
 
@@ -196,6 +200,25 @@ def render_caption_template
           form.render_caption_template(caption_template_name)
         end
 
+        def character_limit?
+          false
+        end
+
+        def character_limit_id
+          ids[:character_limit_caption]
+        end
+
+        def character_limit_target_prefix
+          case type
+          when :text_field
+            "primer-text-field"
+          when :text_area
+            "primer-text-area"
+          else
+            ""
+          end
+        end
+
         def valid?
           supports_validation? && validation_messages.empty? && !@invalid
         end

app/lib/primer/forms/dsl/text_area_input.rb

@@ -5,13 +5,20 @@ module Forms
     module Dsl
       # :nodoc:
       class TextAreaInput < Input
-        attr_reader :name, :label
+        attr_reader :name, :label, :character_limit
 
         def initialize(name:, label:, **system_arguments)
           @name = name
           @label = label
+          @character_limit = system_arguments.delete(:character_limit)
+
+          if @character_limit.present? && @character_limit.to_i <= 0
+            raise ArgumentError, "character_limit must be a positive integer, got #{@character_limit}"
+          end
 
           super(**system_arguments)
+
+          add_input_data(:target, "primer-text-area.inputElement")
         end
 
         def to_component
@@ -22,6 +29,10 @@ def type
           :text_area
         end
 
+        def character_limit?
+          @character_limit.present?
+        end
+
         # :nocov:
         def focusable?
           true

app/lib/primer/forms/dsl/text_field_input.rb

@@ -6,7 +6,7 @@ class TextFieldInput < Input
         attr_reader(
           *%i[
             name label show_clear_button leading_visual leading_spinner trailing_visual clear_button_id
-            visually_hide_label inset monospace field_wrap_classes auto_check_src
+            visually_hide_label inset monospace field_wrap_classes auto_check_src character_limit
           ]
         )
 
@@ -24,6 +24,11 @@ def initialize(name:, label:, **system_arguments)
           @inset = system_arguments.delete(:inset)
           @monospace = system_arguments.delete(:monospace)
           @auto_check_src = system_arguments.delete(:auto_check_src)
+          @character_limit = system_arguments.delete(:character_limit)
+
+          if @character_limit.present? && @character_limit.to_i <= 0
+            raise ArgumentError, "character_limit must be a positive integer, got #{@character_limit}"
+          end
 
           if @leading_visual
             @leading_visual[:classes] = class_names(
@@ -67,6 +72,10 @@ def focusable?
           true
         end
 
+        def character_limit?
+          @character_limit.present?
+        end
+
         def validation_arguments
           if auto_check_src.present?
             super.merge(

app/lib/primer/forms/primer_text_area.ts

@@ -0,0 +1,37 @@
+import {controller, target} from '@github/catalyst'
+import {CharacterCounter} from './character_counter'
+
+@controller
+export class PrimerTextAreaElement extends HTMLElement {
+  @target inputElement: HTMLTextAreaElement
+  @target characterLimitElement: HTMLElement
+  @target characterLimitSrElement: HTMLElement
+
+  #characterCounter: CharacterCounter | null = null
+
+  connectedCallback(): void {
+    if (this.characterLimitElement) {
+      this.#characterCounter = new CharacterCounter(
+        this.inputElement,
+        this.characterLimitElement,
+        this.characterLimitSrElement,
+      )
+      this.#characterCounter.initialize()
+    }
+  }
+
+  disconnectedCallback(): void {
+    this.#characterCounter?.cleanup()
+  }
+}
+
+declare global {
+  interface Window {
+    PrimerTextAreaElement: typeof PrimerTextAreaElement
+  }
+}
+
+if (!window.customElements.get('primer-text-area')) {
+  Object.assign(window, {PrimerTextAreaElement})
+  window.customElements.define('primer-text-area', PrimerTextAreaElement)
+}