Pending Review

Pending Review from User Experience (UX)

Hint Component

Overview

The PWC Hint is a contextual help component in the Progress Web Components design system. It provides informational tooltips with icon indicators for help text and error states across React and Angular applications.

Core Capabilities

Icon Integration - Displays help or warning-diamond icons based on error state
Tooltip Display - Shows contextual information in positioned tooltips on hover/focus
Error State Handling - Visual distinction between informational and error hints
Color Variations - Subtle color for help icons, danger color for error icons
Tooltip Positioning - Right-positioned tooltips with proper anchor alignment
Clickable Interaction - Icons are clickable for improved accessibility and usability

When to use Hint:

Display contextual help information for form fields and interface elements
Show validation errors and warning messages with visual indicators
Provide additional explanatory content without cluttering the main interface
Present tooltips and guidance text for complex features or workflows

When not to use Hint:

Primary content or body text (use Body component for regular text content)
Permanent labels or headings (use Heading component for section titles)
Interactive elements requiring navigation (use Link or Button components)

Basic Implementation

React 18React 19+AngularPure JavaScript

import React, { useState, useCallback } from 'react';
import { PwcHint, PwcFlex, PwcButton, PwcInput } from '@progress-i360/pwc-react';

function FormValidation() {
  const [email, setEmail] = useState('');
  const [showAdvanced, setShowAdvanced] = useState(false);

  // React 18: useCallback for optimization
  const validateEmail = useCallback(() => {
    return email.includes('@') ? null : 'Please enter a valid email address';
  }, [email]);

  const toggleAdvanced = useCallback(() => {
    setShowAdvanced(prev => !prev);
  }, []);

  const error = email ? validateEmail() : null;

  return (
      <PwcFlex direction="column" gap="s">
        <PwcFlex alignItems="center" gap="s">
          <PwcInput
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            placeholder="Enter email"
          />
          <PwcHint 
            hint={showAdvanced ? 
              "Use corporate email for SSO integration" : 
              "Enter your email address"
            }
            heading="Email Help"
            error={!!error}
          />
        </PwcFlex>

        <PwcButton
          label={showAdvanced ? 'Basic Help' : 'Advanced Help'}
          variant="outline"
          onPwcClick={toggleAdvanced}
        />
      </PwcFlex>
  );
}

import { useActionState, useCallback, useEffect, useOptimistic, useRef, useState } from 'react';
import '@progress-i360/progress-web-components/hint';
import '@progress-i360/progress-web-components/flex';
import '@progress-i360/progress-web-components/button';
import '@progress-i360/progress-web-components/input';

type FieldName = 'username' | 'password';

type ValidationErrors = {
  username?: string;
};

type ValidationState = {
  errors: ValidationErrors;
  validated: boolean;
};

function SmartValidation() {
  const [fields, setFields] = useState<Record<FieldName, string>>({ username: '', password: '' });
  const usernameRef = useRef<HTMLElement & { value: string } | null>(null);

  // React 19+: Optimistic field updates
  const [optimisticFields, updateField] = useOptimistic(
    fields,
    (state, { field, value }: { field: FieldName; value: string }) => ({ ...state, [field]: value })
  );

  // React 19+: Form validation action
  const [validationState, validateAction, isPending] = useActionState(
    async (_prev: ValidationState, formData: FormData): Promise<ValidationState> => {
      await new Promise(resolve => setTimeout(resolve, 500));
      const username = formData.get('username')?.toString() ?? '';
      const errors: ValidationErrors = {};

      if (username && username.length < 3) {
        errors.username = 'Username too short';
      }

      return { errors, validated: true };
    },
    { errors: {}, validated: false }
  );

  useEffect(() => {
    if (usernameRef.current) {
      usernameRef.current.value = optimisticFields.username;
    }
  }, [optimisticFields.username]);

  const handleFieldChange = useCallback(
    (field: FieldName, value: string) => {
      updateField({ field, value });
      setFields(prev => ({ ...prev, [field]: value }));
    },
    [updateField, setFields]
  );

  return (
    <form action={validateAction}>
      <pwc-flex direction="column" gap="s">
        <pwc-flex align-items="center" gap="s">
          <pwc-input
            ref={usernameRef}
            name="username"
            placeholder="Username"
            onInput={event => handleFieldChange('username', (event.target as HTMLInputElement).value)}
          ></pwc-input>
          <pwc-hint
            hint={validationState.errors.username ?? 'Minimum 3 characters required'}
            heading="Username Requirements"
            error={validationState.errors.username ? 'true' : undefined}
          ></pwc-hint>
        </pwc-flex>

        <pwc-button
          type="submit"
          label={isPending ? 'Validating...' : 'Validate'}
          variant="primary"
          disabled={isPending}
        ></pwc-button>
      </pwc-flex>
    </form>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@progress-i360/progress-web-components/hint";
import "@progress-i360/progress-web-components/flex";
import "@progress-i360/progress-web-components/button";
import "@progress-i360/progress-web-components/body";
import "@progress-i360/progress-web-components/heading";

@Component({
  selector: 'hint-demo',
  template: `
    <pwc-flex direction="column" gap="m" padding="m">
      <pwc-heading content="Form Field with Hints" size="l"></pwc-heading>
      <pwc-flex align-items="center" gap="s">
        <pwc-body content="Username"></pwc-body>
        <pwc-hint [hint]="helpHint" heading="Help"></pwc-hint>
      </pwc-flex>
      <pwc-flex align-items="center" gap="s">
        <pwc-body content="Password" [color]="hasError ? 'red-base' : 'base'"></pwc-body>
        <pwc-hint [hint]="errorHint" [error]="hasError" *ngIf="hasError"></pwc-hint>
      </pwc-flex>
      <pwc-flex gap="s">
        <pwc-button label="Toggle Error" variant="outline" (pwc-click)="toggleError()"></pwc-button>
        <pwc-button label="Update Help" variant="primary" (pwc-click)="updateHelp()"></pwc-button>
      </pwc-flex>
    </pwc-flex>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class HintDemo {
  helpHint = 'Enter at least 3 characters for your username';
  errorHint = 'Password must be at least 8 characters long';
  hasError = false;
  helpCount = 0;

  toggleError() {
    this.hasError = !this.hasError;
  }

  updateHelp() {
    this.helpCount++;
    this.helpHint = `Updated help text #${this.helpCount}: Username requirements may vary`;
  }
}

import '@progress-i360/progress-web-components/hint';

const helpHint = document.createElement('pwc-hint');
helpHint.setAttribute('hint', 'Enter your email address');
helpHint.setAttribute('heading', 'Help');

const errorHint = document.createElement('pwc-hint');
errorHint.setAttribute('hint', 'This field is required');
errorHint.setAttribute('error', 'true');

const warningHint = document.createElement('pwc-hint');
warningHint.setAttribute('hint', 'Changes to this setting will affect all users in your organization');
warningHint.setAttribute('variant', 'warning');
warningHint.setAttribute('icon', 'alert-triangle');

document.querySelector('#email-field')?.appendChild(helpHint);
document.querySelector('#password-field')?.appendChild(errorHint);
document.querySelector('#settings-field')?.appendChild(warningHint);

Usage Patterns

Hint components adapt to different contextual help scenarios:

Informational Hints - Display help icons with explanatory tooltips for guidance
Error State Hints - Show warning-diamond icons with error messages for validation
Tooltip Positioning - Right-positioned tooltips with proper anchor alignment
Interactive Elements - Clickable icons for improved accessibility and user interaction

Best Practices

Content Strategy Guidelines

Clear Messaging - Write concise, actionable text that directly addresses user needs
Contextual Relevance - Provide hints that offer value specific to the current task
Consistent Tone - Use helpful, instructional language that guides rather than criticizes
Progressive Detail - Offer appropriate level of information depth for the context

Performance Optimization

Efficient Rendering - Lightweight tooltip rendering that doesn't impact page performance
Icon Loading - Optimize icon assets for fast loading and consistent display
Memory Management - Proper cleanup and state management for dynamic tooltip content
Event Handling - Efficient hover and click event management for interactive icons

Integration Architecture

Component Dependencies - Seamless integration with PWC Icon and Tooltip components
Error State Management - Boolean error property controls visual state and icon selection
Positioning System - Right-positioned tooltips with proper anchor alignment
Accessibility Support - Proper ARIA labeling and keyboard focus management

Common Use Cases

Data Table Headers

Column Help Text - Explanatory hints for complex data column meanings and calculations
Filter Guidance - Help icons explaining filter options and search functionality
Action Clarification - Tooltips for table action buttons and bulk operation controls

Search Result Sections

Search Tips - Help hints explaining search syntax and advanced filter options
Result Context - Information icons providing context about search result relevance
Error Guidance - Error state hints for invalid search queries with correction suggestions

Metric Explanations - Help icons explaining dashboard metrics and calculation methods
Configuration Help - Guidance hints for widget settings and customization options
Status Indicators - Error and warning hints for widget data issues or connectivity problems

Troubleshooting

Common Issues

Hint Not Displaying

Problem: Hint tooltip doesn't appear on hover or click

Solution:

Verify hint property is set correctly and tooltip component is properly initialized

Icon Not Showing

Problem: Help or warning icons don't display correctly

Solution:

Check error property boolean value and ensure icon components are imported

Problem: Tooltip appears in wrong position or gets cut off

Solution:

Verify anchor element positioning and check for container overflow constraints

Accessibility Problems

Problem: Hint content not accessible to screen readers

Solution:

Ensure proper ARIA labeling and keyboard focus management for clickable icons

Implementation Support

For detailed implementation guidance:

Icon Integration - Works seamlessly with PWC Icon component for visual indicators
Tooltip Dependencies - Leverages PWC Tooltip component for content display
Error State Management - Boolean error property controls visual state and icon selection

Resources

Storybook Documentation

For comprehensive API documentation, interactive examples, and testing tools: 📖 View Complete API Documentation in Storybook →

Hint Component

Overview

Core Capabilities

Basic Implementation

Usage Patterns

Best Practices

Content Strategy Guidelines

Performance Optimization

Integration Architecture

Common Use Cases

Data Table Headers

Search Result Sections

Dashboard Widget Headers

Troubleshooting

Common Issues

Hint Not Displaying

Icon Not Showing

Tooltip Positioning Issues

Accessibility Problems

Implementation Support

Resources

Storybook Documentation