@pushwoosh/dumb-components 1.1.147 → 1.1.149

package/PageHeader/ai-documentation.md

@@ -1,511 +0,0 @@
-# PageHeader Component System - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: PageHeader (System)
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/PageHeader/index.ts` - Main exports
-  - `/src/PageHeader/components/PageHeader/` - Main page header component
-  - `/src/PageHeader/components/PageHeaderEditable/` - Editable page header variant
-  - `/src/PageHeader/components/PageHeaderError/` - Error display component
-  - `/src/PageHeader/components/PageHeaderSkeleton/` - Loading skeleton
-  - `/src/PageHeader/components/AutosizeInput/` - Auto-sizing input field
-- **Type**: Layout/Navigation
-- **Description**: A comprehensive page header system with title, description, actions, error handling, and editable variants. Provides consistent page-level navigation and action patterns.
-
-## TypeScript Interfaces
-
-```typescript
-// Main PageHeader component
-export interface PageHeaderProps {
-  title: ReactNode;
-  description?: ReactNode | string;
-  error?: string;
-  resolveErrorText?: string;
-  submitText?: string;
-  cancelText?: string;
-  isLoadingSubmit?: boolean;
-  moreActions?: ReactElement;
-  onBack?: () => void;
-  onSubmit?: (params?: any) => void;
-  onCancel?: () => void;
-  onResolveError?: () => void;
-}
-
-// Editable PageHeader variant
-export interface PageHeaderEditableProps {
-  title: string;
-  description?: string;
-  error?: string;
-  resolveErrorText?: string;
-  value?: string;
-  maxLength?: number;
-  placeholder?: string;
-  submitText?: string;
-  cancelText?: string;
-  isLoading?: boolean;
-  isLoadingSubmit?: boolean;
-  moreActions?: ReactElement;
-  onBack?: () => void;
-  onChange?: (value: string) => void;
-  onComplete?: (value: string) => void;
-  onSubmit?: (value: string) => void;
-  onCancel?: () => void;
-  onResolveError?: () => void;
-}
-
-// Error component
-export interface PageHeaderErrorProps {
-  error: string;
-  resolveErrorText?: string | undefined;
-  onResolveError?: (() => void) | undefined;
-}
-
-// AutosizeInput component
-export interface AutosizeInputProps {
-  value: string;
-  placeholder?: string | undefined;
-  maxLength?: number | undefined;
-  onChange?: ((value: string) => void) | undefined;
-  onComplete?: ((value: string) => void) | undefined;
-}
-```
-
-## Import & Usage
-
-```typescript
-import { PageHeader, PageHeaderEditable, AutosizeInput } from '@pushwoosh/dumb-components';
-
-// Basic page header
-function BasicPage() {
-  return (
-    <div>
-      <PageHeader
-        title="Dashboard"
-        description="Overview of your application metrics and performance"
-      />
-      <main>
-        {/* Page content */}
-      </main>
-    </div>
-  );
-}
-
-// Page header with back navigation
-function DetailPage() {
-  const navigate = useNavigate();
-
-  return (
-    <div>
-      <PageHeader
-        title="User Details"
-        description="Manage user profile and settings"
-        onBack={() => navigate(-1)}
-      />
-      <main>
-        {/* User details content */}
-      </main>
-    </div>
-  );
-}
-
-// Page header with actions
-function EditablePage() {
-  const [isLoading, setIsLoading] = useState(false);
-
-  const handleSubmit = async () => {
-    setIsLoading(true);
-    try {
-      await saveChanges();
-      // Handle success
-    } catch (error) {
-      // Handle error
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  return (
-    <div>
-      <PageHeader
-        title="Edit Profile"
-        description="Update your personal information"
-        submitText="Save Changes"
-        cancelText="Cancel"
-        isLoadingSubmit={isLoading}
-        onBack={() => navigate('/profile')}
-        onSubmit={handleSubmit}
-        onCancel={() => navigate('/profile')}
-      />
-      <main>
-        {/* Edit form */}
-      </main>
-    </div>
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Page header with error handling
-function PageWithError() {
-  const [error, setError] = useState('');
-
-  const handleResolveError = () => {
-    setError('');
-    // Retry failed operation
-    retryOperation();
-  };
-
-  return (
-    <div>
-      <PageHeader
-        title="Data Import"
-        description="Import data from external sources"
-        error={error}
-        resolveErrorText="Retry Import"
-        onResolveError={handleResolveError}
-        onSubmit={handleImport}
-      />
-      <main>
-        {/* Import interface */}
-      </main>
-    </div>
-  );
-}
-
-// Editable page header
-function EditablePageTitle() {
-  const [title, setTitle] = useState('Untitled Document');
-  const [isEditing, setIsEditing] = useState(false);
-  const [isSaving, setIsSaving] = useState(false);
-
-  const handleSubmit = async (newTitle: string) => {
-    setIsSaving(true);
-    try {
-      await updateDocumentTitle(newTitle);
-      setTitle(newTitle);
-      setIsEditing(false);
-    } catch (error) {
-      // Handle error
-    } finally {
-      setIsSaving(false);
-    }
-  };
-
-  if (isEditing) {
-    return (
-      <PageHeaderEditable
-        title="Edit Document Title"
-        description="Enter a descriptive title for your document"
-        value={title}
-        placeholder="Enter document title..."
-        maxLength={100}
-        submitText="Save"
-        cancelText="Cancel"
-        isLoadingSubmit={isSaving}
-        onSubmit={handleSubmit}
-        onCancel={() => setIsEditing(false)}
-      />
-    );
-  }
-
-  return (
-    <PageHeader
-      title={title}
-      description="Your document content goes here"
-      moreActions={
-        <Button 
-          color="secondary" 
-          view="ghost"
-          onClick={() => setIsEditing(true)}
-        >
-          Edit Title
-        </Button>
-      }
-    />
-  );
-}
-
-// Complex page header with multiple actions
-function ProjectPage() {
-  const [project, setProject] = useState(null);
-  const [isPublishing, setIsPublishing] = useState(false);
-  const [error, setError] = useState('');
-
-  const moreActions = (
-    <>
-      <Button 
-        color="secondary" 
-        view="ghost"
-        icon={<ShareIcon />}
-        onClick={handleShare}
-      >
-        Share
-      </Button>
-      <Button 
-        color="secondary" 
-        view="ghost"
-        icon={<DuplicateIcon />}
-        onClick={handleDuplicate}
-      >
-        Duplicate
-      </Button>
-      <Button 
-        color="danger" 
-        view="ghost"
-        icon={<DeleteIcon />}
-        onClick={handleDelete}
-      >
-        Delete
-      </Button>
-    </>
-  );
-
-  return (
-    <div>
-      <PageHeader
-        title={project?.name || 'Untitled Project'}
-        description={`Created ${formatDate(project?.createdAt)} • Last modified ${formatDate(project?.updatedAt)}`}
-        error={error}
-        resolveErrorText="Retry"
-        submitText="Publish"
-        cancelText="Save Draft"
-        isLoadingSubmit={isPublishing}
-        moreActions={moreActions}
-        onBack={() => navigate('/projects')}
-        onSubmit={() => handlePublish()}
-        onCancel={() => handleSaveDraft()}
-        onResolveError={() => setError('')}
-      />
-      <main>
-        {/* Project editor */}
-      </main>
-    </div>
-  );
-}
-
-// Form page with validation
-function FormPage() {
-  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm();
-  const [submitError, setSubmitError] = useState('');
-
-  const onSubmit = async (data: any) => {
-    setSubmitError('');
-    try {
-      await submitForm(data);
-      navigate('/success');
-    } catch (error) {
-      setSubmitError('Failed to submit form. Please try again.');
-    }
-  };
-
-  const hasFormErrors = Object.keys(errors).length > 0;
-
-  return (
-    <div>
-      <PageHeader
-        title="Create Account"
-        description="Fill out the form below to create your new account"
-        error={submitError || (hasFormErrors ? 'Please fix the errors below' : '')}
-        resolveErrorText="Try Again"
-        submitText="Create Account"
-        cancelText="Cancel"
-        isLoadingSubmit={isSubmitting}
-        onBack={() => navigate('/login')}
-        onSubmit={handleSubmit(onSubmit)}
-        onCancel={() => navigate('/login')}
-        onResolveError={() => setSubmitError('')}
-      />
-      
-      <form>
-        <input 
-          {...register('email', { required: 'Email is required' })}
-          placeholder="Email address"
-        />
-        {errors.email && <span>{errors.email.message}</span>}
-        
-        <input 
-          {...register('password', { required: 'Password is required' })}
-          type="password"
-          placeholder="Password"
-        />
-        {errors.password && <span>{errors.password.message}</span>}
-      </form>
-    </div>
-  );
-}
-
-// Wizard-style navigation
-function WizardPage() {
-  const [currentStep, setCurrentStep] = useState(1);
-  const totalSteps = 4;
-  
-  const stepTitles = {
-    1: 'Basic Information',
-    2: 'Contact Details', 
-    3: 'Preferences',
-    4: 'Review & Submit'
-  };
-
-  const handleNext = () => {
-    if (currentStep < totalSteps) {
-      setCurrentStep(prev => prev + 1);
-    } else {
-      handleSubmit();
-    }
-  };
-
-  const handleBack = () => {
-    if (currentStep > 1) {
-      setCurrentStep(prev => prev - 1);
-    } else {
-      navigate('/dashboard');
-    }
-  };
-
-  return (
-    <div>
-      <PageHeader
-        title={stepTitles[currentStep]}
-        description={`Step ${currentStep} of ${totalSteps}`}
-        submitText={currentStep === totalSteps ? 'Submit' : 'Next'}
-        cancelText={currentStep === 1 ? 'Cancel' : 'Back'}
-        onBack={currentStep === 1 ? () => navigate('/dashboard') : undefined}
-        onSubmit={handleNext}
-        onCancel={handleBack}
-      />
-      
-      <main>
-        {/* Step content */}
-        <div>Step {currentStep} content here</div>
-      </main>
-    </div>
-  );
-}
-```
-
-## Props Reference
-
-### PageHeader
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `title` | `ReactNode` | - | Yes | Main page title |
-| `description` | `ReactNode \| string` | `undefined` | No | Optional description below title |
-| `error` | `string` | `undefined` | No | Error message to display |
-| `resolveErrorText` | `string` | `undefined` | No | Text for error resolution button |
-| `submitText` | `string` | `'Create'` | No | Text for submit button |
-| `cancelText` | `string` | `'Cancel'` | No | Text for cancel button |
-| `isLoadingSubmit` | `boolean` | `false` | No | Whether submit button shows loading state |
-| `moreActions` | `ReactElement` | `undefined` | No | Additional action buttons |
-| `onBack` | `() => void` | `undefined` | No | Callback for back navigation |
-| `onSubmit` | `(params?: any) => void` | `undefined` | No | Callback for submit action |
-| `onCancel` | `() => void` | `undefined` | No | Callback for cancel action |
-| `onResolveError` | `() => void` | `undefined` | No | Callback for error resolution |
-
-### PageHeaderEditable
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `title` | `string` | - | Yes | Page title (non-editable) |
-| `description` | `string` | `undefined` | No | Optional description |
-| `error` | `string` | `undefined` | No | Error message |
-| `resolveErrorText` | `string` | `undefined` | No | Error resolution button text |
-| `value` | `string` | `undefined` | No | Current input value |
-| `maxLength` | `number` | `undefined` | No | Maximum input length |
-| `placeholder` | `string` | `undefined` | No | Input placeholder text |
-| `submitText` | `string` | `'Create'` | No | Submit button text |
-| `cancelText` | `string` | `'Cancel'` | No | Cancel button text |
-| `isLoading` | `boolean` | `false` | No | General loading state |
-| `isLoadingSubmit` | `boolean` | `false` | No | Submit button loading state |
-| `moreActions` | `ReactElement` | `undefined` | No | Additional actions |
-| `onBack` | `() => void` | `undefined` | No | Back navigation callback |
-| `onChange` | `(value: string) => void` | `undefined` | No | Input change callback |
-| `onComplete` | `(value: string) => void` | `undefined` | No | Input completion callback |
-| `onSubmit` | `(value: string) => void` | `undefined` | No | Form submit callback |
-| `onCancel` | `() => void` | `undefined` | No | Cancel callback |
-| `onResolveError` | `() => void` | `undefined` | No | Error resolution callback |
-
-### AutosizeInput
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `value` | `string` | - | Yes | Input value |
-| `placeholder` | `string` | `undefined` | No | Placeholder text |
-| `maxLength` | `number` | `undefined` | No | Maximum character length |
-| `onChange` | `(value: string) => void` | `undefined` | No | Change callback |
-| `onComplete` | `(value: string) => void` | `undefined` | No | Completion callback (Enter key) |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **Consistent Navigation**: Use back buttons for hierarchical navigation
-```typescript
-<PageHeader
-  title="User Details"
-  onBack={() => navigate('/users')}
-/>
-```
-
-2. **Action Placement**: Place primary actions on the right, secondary actions in moreActions
-```typescript
-<PageHeader
-  title="Edit Profile"
-  submitText="Save Changes"
-  cancelText="Cancel"
-  moreActions={<Button view="ghost">Preview</Button>}
-  onSubmit={handleSave}
-  onCancel={handleCancel}
-/>
-```
-
-3. **Error Handling**: Provide clear error messages with resolution actions
-```typescript
-<PageHeader
-  title="Import Data"
-  error="Connection failed"
-  resolveErrorText="Retry Connection"
-  onResolveError={handleRetry}
-/>
-```
-
-### Common Mistakes to Avoid
-
-1. **Missing Hierarchy**: Don't use back buttons on top-level pages
-2. **Inconsistent Actions**: Keep submit/cancel patterns consistent across the app
-3. **Unclear Titles**: Use descriptive, action-oriented titles
-4. **Missing Loading States**: Always handle loading states for async actions
-5. **Too Many Actions**: Limit primary actions to 2-3, move others to moreActions
-
-### Integration Tips
-
-1. **Routing Integration**: Works well with React Router for navigation
-```typescript
-const navigate = useNavigate();
-<PageHeader onBack={() => navigate(-1)} />
-```
-
-2. **Form Integration**: Coordinates well with form libraries
-```typescript
-const { handleSubmit, formState: { isSubmitting } } = useForm();
-
-<PageHeader
-  onSubmit={handleSubmit(onSubmit)}
-  isLoadingSubmit={isSubmitting}
-/>
-```
-
-3. **State Management**: Integrates with global state for error handling
-4. **Accessibility**: Components include proper ARIA labels and keyboard navigation
-5. **Responsive**: Layout adapts to different screen sizes automatically
-
-## Related Components
-
-- **Button**: Used internally for actions
-- **Modal**: For modal dialogs with similar header patterns
-- **Breadcrumb**: For more complex navigation hierarchies
-- **Tabs**: For sub-page navigation within the same level