anton-bakker-amplify-components

A comprehensive React UI component library for AWS Amplify applications, providing CRUD operations, data visualization, and enhanced user experience features.

🚀 Features

Core Components

• CRUD Operations: Complete Create, Read, Update, Delete functionality
• Auto-detection: Automatic field detection from Amplify schemas
• Data Visualization: KPI cards, bar charts, and pie charts
• Search & Filtering: Advanced search modals and field filters
• Auto-save: Real-time form auto-saving capabilities
• Address Lookup: Location services integration

Quality & Reliability

• Zero Console Logging: Clean production builds without debug output
• Error Boundaries: Graceful error handling with user-friendly alerts
• TypeScript: Full type safety and IntelliSense support
• Peer Dependencies: Lightweight bundle, leverages your existing Amplify setup

📦 Installation

npm install anton-bakker-amplify-components

Peer Dependencies

Install these required dependencies in your application:

npm install aws-amplify@^6 react@^18 react-dom@^18 @aws-amplify/ui-react@^6 @tanstack/react-query@^5

🏗️ Quick Start

Basic CRUD Operations

import { DefaultListPage, DefaultCreatePage, DefaultUpdatePage } from 'anton-bakker-amplify-components';

// List page with auto-detected columns
<DefaultListPage
  modelName="Product"
  columns="auto"
/>

// Create page with auto-detected fields
<DefaultCreatePage
  modelName="Product"
  fields="auto"
/>

// Update page with custom field overrides
<DefaultUpdatePage
  modelName="Product"
  fields="auto"
  fieldOverrides={{
    price: { type: 'number', info: 'Price in USD' },
    email: { info: 'Valid email address required' }
  }}
/>

Data Visualization

import { KPIDashboard, SimpleBarChart, SimplePieChart } from 'anton-bakker-amplify-components';

// KPI Dashboard
<KPIDashboard
  kpis={[
    { title: 'Total Sales', value: 125000, format: 'currency' },
    { title: 'Active Users', value: 1250, format: 'number' },
    { title: 'Growth Rate', value: 15.5, format: 'percentage' }
  ]}
/>

// Bar Chart
<SimpleBarChart
  data={[
    { label: 'Q1', value: 100 },
    { label: 'Q2', value: 150 },
    { label: 'Q3', value: 200 }
  ]}
  title="Quarterly Sales"
/>

Advanced Search

import { HybridSearchModal, SearchModal } from 'anton-bakker-amplify-components';

// Hybrid search with filters
<HybridSearchModal
  modelName="Product"
  searchFields={['name', 'description']}
  filters={[
    { field: 'category', type: 'select', options: categoryOptions },
    { field: 'price', type: 'range', min: 0, max: 1000 }
  ]}
  onSelect={handleProductSelect}
/>

Auto-save Forms

import { AutoSaveProvider, AutoSaveTextField } from 'anton-bakker-amplify-components';

<AutoSaveProvider>
  <AutoSaveTextField
    name="title"
    label="Product Title"
    saveEndpoint="/api/products/123"
  />
</AutoSaveProvider>

📚 Component Reference

CRUD Components

| Component | Purpose | Key Props | |-----------|---------|-----------| | DefaultListPage | Data table with pagination, sorting, filtering | modelName, columns, filters | | DefaultCreatePage | Form for creating new records | modelName, fields, fieldOverrides | | DefaultUpdatePage | Form for editing existing records | modelName, fields, recordId | | DefaultRetrievePage | Read-only record display | modelName, recordId, fields | | GenericCrudPage | All-in-one CRUD interface | modelName, mode | | GenericCrudModal | Modal-based CRUD operations | modelName, isOpen, mode |

Data Visualization

| Component | Purpose | Key Props | |-----------|---------|-----------| | KPICard | Single metric display | title, value, format, trend | | KPIDashboard | Multiple KPI cards layout | kpis, columns | | SimpleBarChart | Bar chart visualization | data, title, xAxisLabel | | SimplePieChart | Pie chart visualization | data, title, showLegend |

Search & Filtering

| Component | Purpose | Key Props | |-----------|---------|-----------| | SearchModal | Basic search interface | modelName, searchFields, onSelect | | HybridSearchModal | Advanced search with filters | modelName, searchFields, filters | | FieldFilter | Individual field filter | field, type, options, onChange |

Auto-save & Forms

| Component | Purpose | Key Props | |-----------|---------|-----------| | AutoSaveProvider | Context for auto-save functionality | debounceMs, onSave | | AutoSaveTextField | Text field with auto-save | name, saveEndpoint, debounceMs | | AutoSaveIndicator | Visual feedback for save status | status, lastSaved |

Utility Components

| Component | Purpose | Key Props | |-----------|---------|-----------| | AddressLookup | Location search and selection | onSelect, placeholder, region | | ProtectedRoute | Route-based access control | children, requiredPermissions | | DefaultDarkMode | Theme toggle component | defaultTheme | | Tooltip | Information tooltips | content, children | | FieldLabel | Enhanced form labels | label, required, info |

🔧 Configuration

Field Auto-detection

The library can automatically detect fields from your Amplify schema:

// Auto-detect all fields
<DefaultCreatePage
  modelName="Product"
  fields="auto"
/>

// Auto-detect with exclusions
<DefaultCreatePage
  modelName="Product"
  fields="auto"
  excludeFields={['internalNotes', 'createdAt']}
/>

// Auto-detect with overrides
<DefaultCreatePage
  modelName="Product"
  fields="auto"
  fieldOverrides={{
    email: { 
      type: 'email', 
      info: 'Valid email address required',
      placeholder: '[email protected]'
    },
    phone: {
      type: 'tel',
      info: 'International format recommended',
      placeholder: '+1 (555) 123-4567'
    }
  }}
/>

Custom Actions

Add custom actions to list pages:

<DefaultListPage
  modelName="Product"
  customActions={[
    {
      label: 'Export CSV',
      icon: <DownloadIcon />,
      onClick: handleExport,
      variant: 'primary'
    },
    {
      label: 'Bulk Import',
      icon: <UploadIcon />,
      onClick: handleImport,
      variant: 'secondary'
    }
  ]}
/>

Filtering & Search

Configure advanced filtering:

<DefaultListPage
  modelName="Product"
  filters={[
    {
      field: 'category',
      type: 'select',
      label: 'Category',
      options: [
        { value: 'electronics', label: 'Electronics' },
        { value: 'clothing', label: 'Clothing' }
      ]
    },
    {
      field: 'price',
      type: 'range',
      label: 'Price Range',
      min: 0,
      max: 1000
    },
    {
      field: 'name',
      type: 'text',
      label: 'Product Name',
      placeholder: 'Search by name...'
    }
  ]}
  filterLayout="sidebar" // or "toolbar" or "auto"
/>

🎨 Styling & Theming

The library uses AWS Amplify UI React components and inherits your application's theme:

import { ThemeProvider } from '@aws-amplify/ui-react';
import { myCustomTheme } from './theme';

<ThemeProvider theme={myCustomTheme}>
  <DefaultListPage modelName="Product" />
</ThemeProvider>

🧪 Testing

The library includes comprehensive tests and supports testing in your application:

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Testing Your Components

import { render, screen } from '@testing-library/react';
import { DefaultCreatePage } from 'anton-bakker-amplify-components';

test('renders create form', () => {
  render(
    <DefaultCreatePage
      modelName="Product"
      fields={[
        { name: 'name', label: 'Name', type: 'text', required: true }
      ]}
    />
  );
  
  expect(screen.getByLabelText(/Name/)).toBeInTheDocument();
});

🚀 Publishing

For maintainers, the library uses automated publishing with AWS Secrets Manager:

# One-time setup
aws --profile BeyondAmbition secretsmanager create-secret \
  --name npm/automation-token/anton-bakker-amplify-components \
  --secret-string '<your-npm-automation-token>'

# Publish new version
AWS_PROFILE=BeyondAmbition npm run release:publish

📖 Documentation

• Implementation Guide - Detailed implementation examples
• API Design Decisions - Architecture and design rationale
• Enhancement Proposals - Future roadmap

🔄 Changelog

v2.1.77 (Latest)

• Enhanced HybridSearchModal with improved filtering
• Updated DefaultListPage with better pagination
• Added comprehensive TypeScript types
• Improved auto-save functionality

v2.0.0

• BREAKING: Removed console logging from all components
• BREAKING: Error handling now uses alerts instead of thrown exceptions
• BREAKING: Moved aws-amplify to peerDependencies
• Added auto-detection for fields and columns
• Introduced data visualization components
• Enhanced search and filtering capabilities

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: npm test
5. Commit using conventional commits: git commit -m "feat: add amazing feature"
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Create an issue for bug reports or feature requests
• Check existing documentation in the /docs folder
• Review test files in /src/__tests__ for usage examples