Package Exports

ui-syntheticaia

Readme

🎨 ui-syntheticaia

Professional React UI Component Library for Enterprise Dashboards

Modern React component library built with cutting-edge technologies for the Synthetica Suite ecosystem. Features 92+ components, 412+ interactive stories, and enterprise-grade accessibility compliance.

🚀 Key Features

🎯 Enterprise-Ready Components

92+ Components organized using Atomic Design principles
412+ Interactive Stories with comprehensive documentation
3 Advanced Components: FilterBuilder, BulkActions, FormBuilder
Multi-tenant Architecture support built-in

🔧 Modern Tech Stack

React 19.1+ with latest Suspense improvements
TypeScript 5.9+ strict mode with zero any types
Tailwind CSS 3.4+ with dark/light/system themes
Storybook 9.1+ with accessibility testing
Vite 7.1+ build system with tree-shaking

♿ Accessibility First

85% WCAG 2.1 AA compliance (target: 100%)
Screen reader compatible with proper ARIA labels
Keyboard navigation support throughout
Automated accessibility testing with axe-core

📦 Developer Experience

TypeScript-first with comprehensive type definitions
Tree-shakeable imports for optimal bundle sizes
Zero runtime dependencies (peer dependencies only)
Hot Module Replacement support

📋 Component Architecture

🏗️ Atomic Design Structure

src/components/
├── atoms/           # 7 basic components
│   ├── Button.tsx
│   ├── Input.tsx
│   ├── Icon.tsx
│   └── ...
├── molecules/       # 5 composite components
│   ├── Card.tsx
│   ├── SearchBox.tsx
│   └── ...
├── organisms/       # 4 complex components
│   ├── DataTable.tsx
│   ├── Header.tsx
│   └── ...
├── templates/       # 4 page templates
│   ├── DashboardTemplate.tsx
│   └── ...
├── dashboard/       # 6 dashboard components
│   ├── MetricCard.tsx
│   ├── Chart.tsx
│   └── ...
├── advanced/        # 11 advanced components
│   ├── FilterBuilder.tsx ✨
│   ├── BulkActions.tsx ✨
│   ├── FormBuilder.tsx ✨
│   └── ...
├── modules/         # 4 business modules
│   ├── PDV/
│   ├── CRM/
│   └── ...
└── ui/             # 54+ Shadcn/UI base components

⭐ Featured Advanced Components

🔍 FilterBuilder (7 stories)

import { FilterBuilder } from 'ui-syntheticaia'

<FilterBuilder
  fields={[
    { name: 'name', label: 'Nome', type: 'text' },
    { name: 'age', label: 'Idade', type: 'number' },
  ]}
  onFiltersChange={(filters) => console.log(filters)}
  allowGrouping={true}
  showSQLPreview={true}
/>

Drag-and-drop filter construction
Nested groups with AND/OR logic
SQL preview generation
Real-time validation

⚡ BulkActions (9 stories)

import { BulkActions } from 'ui-syntheticaia'

<BulkActions
  selectedItems={[1, 2, 3]}
  actions={[
    { id: 'delete', label: 'Excluir', icon: 'Trash', variant: 'destructive' },
    { id: 'export', label: 'Exportar', icon: 'Download' },
  ]}
  onAction={(actionId, items) => handleBulkAction(actionId, items)}
  showProgress={true}
  maxItems={100}
/>

Mass operations with progress tracking
Confirmation dialogs with rollback support
Permission-based action visibility
Customizable actions with icons

📝 FormBuilder (10 stories)

import { FormBuilder } from 'ui-syntheticaia'

<FormBuilder
  schema={{
    type: 'object',
    properties: {
      name: { type: 'string', title: 'Nome', required: true },
      email: { type: 'email', title: 'E-mail' },
    }
  }}
  onSubmit={(data) => console.log(data)}
  layout="grid"
  columns={2}
  showProgress={true}
/>

Dynamic form generation from JSON schemas
Multi-step wizard flows
15+ field types (text, select, date, rich text, etc.)
Grid layout with responsive columns

🚀 Quick Start

Installation

npm install ui-syntheticaia
# or
yarn add ui-syntheticaia
# or
pnpm add ui-syntheticaia

Setup

// 1. Install peer dependencies
npm install react react-dom @types/react @types/react-dom

// 2. Import CSS (required)
import 'ui-syntheticaia/styles'

// 3. Setup theme provider
import { ThemeProvider } from 'ui-syntheticaia'

function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  )
}

Basic Usage

import { Button, Card, DataTable, MetricCard } from 'ui-syntheticaia'

function Dashboard() {
  return (
    <div className="space-y-6">
      <div className="grid grid-cols-4 gap-4">
        <MetricCard
          title="Total Users"
          value="12,345"
          trend={{ value: 12.5, direction: 'up' }}
          icon="Users"
        />
      </div>

      <Card>
        <DataTable
          data={users}
          columns={userColumns}
          searchable
          sortable
          pagination
        />
      </Card>

      <Button variant="default" size="lg">
        Get Started
      </Button>
    </div>
  )
}

🎨 Theming & Customization

Built-in Themes

Light Theme - Clean and professional
Dark Theme - Modern dark interface
System Theme - Follows OS preference
High Contrast - Enhanced accessibility

Custom Themes

import { ThemeProvider } from 'ui-syntheticaia'

const customTheme = {
  colors: {
    primary: 'hsl(221 83% 53%)',
    secondary: 'hsl(210 40% 96%)',
    // ... more colors
  }
}

<ThemeProvider theme={customTheme}>
  <App />
</ThemeProvider>

CSS Variables

:root {
  --primary: 221 83% 53%;
  --secondary: 210 40% 96%;
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  /* ... */
}

📚 Documentation & Storybook

Interactive Documentation

Explore all 412+ stories in our comprehensive Storybook:

npm run storybook
# Opens http://localhost:6006

Component Examples

Each component includes:

Props documentation with TypeScript definitions
Usage examples covering common scenarios
Accessibility guidelines and testing
Design variations and states

API Reference

Button Component

interface ButtonProps {
  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
  size?: 'default' | 'sm' | 'lg' | 'icon'
  disabled?: boolean
  loading?: boolean
  children: React.ReactNode
}

DataTable Component

interface DataTableProps<TData> {
  data: TData[]
  columns: ColumnDef<TData>[]
  searchable?: boolean
  sortable?: boolean
  pagination?: boolean
  pageSize?: number
  onRowClick?: (row: TData) => void
}

♿ Accessibility

WCAG 2.1 AA Compliance: 85%

Our commitment to accessibility includes:

Semantic HTML structure throughout
ARIA labels and roles properly implemented
Keyboard navigation support for all interactive elements
Screen reader compatibility tested
Color contrast ratios meeting WCAG AA standards
Focus management in complex components

Accessibility Testing

# Run accessibility audit
npm run a11y:audit

# Quick accessibility check
npm run a11y:quick

# Generate HTML report
npm run a11y:report

NVDA - Fully supported
JAWS - Fully supported
VoiceOver - Fully supported

🌐 Multi-tenant Support

Built for enterprise SaaS applications:

// Tenant-aware component usage
<DataTable
  data={data}
  tenantId="tenant-123"
  tenantPlan="enterprise"
  multiTenant={{
    isolation: 'strict',
    branding: customBranding
  }}
/>

Features

Complete data isolation per tenant
Custom branding support
Plan-based feature toggling
Tenant-aware caching

🔧 Development & Contributing

Development Setup

# Clone the repository
git clone https://github.com/Daniel-SyntheticaIA/ui-syntheticaia.git

# Install dependencies
npm install

# Start development
npm run storybook

# Run tests
npm run test

# Build library
npm run build

Scripts

npm run build          # Build library for production
npm run storybook      # Start Storybook development server
npm run a11y:audit     # Run accessibility audit
npm run lint           # ESLint validation
npm run typecheck      # TypeScript validation

Project Structure

ui-syntheticaia/
├── src/
│   ├── components/    # All components organized by atomic design
│   ├── hooks/         # Reusable React hooks
│   ├── lib/           # Utility functions
│   ├── styles/        # Global styles and themes
│   └── utils/         # Helper utilities
├── .storybook/        # Storybook configuration
├── scripts/           # Build and automation scripts
└── dist/              # Built library (generated)

🏗️ Integration with Synthetica Suite

This library is the visual foundation for the complete Synthetica Suite:

Core Integration

core-syntheticaia - NestJS backend APIs
site-syntheticaia - Next.js marketing site
crud-syntheticaia - CRUD operations engine

Future Modules

PDV-Synthetica - Point of Sale system
CRM-Synthetica - Customer management
Estoque-Synthetica - Inventory management
Agentes-Synthetica - AI autonomous agents

📊 Performance

Bundle Analysis

Main Bundle: 1.05MB (247KB gzipped)
Tree-shakeable: Import only what you use
Zero runtime deps: Optimized for production

Optimization Features

Code splitting support
Lazy loading components
Memoized components for performance
Efficient re-renders with React 19

🔄 Versioning & Releases

Current Version: 2.0.0

This major release includes:

✅ React 19 upgrade
✅ 3 Advanced Components (FilterBuilder, BulkActions, FormBuilder)
✅ 85% Accessibility compliance
✅ 412+ Stories comprehensive documentation
✅ SearchBox standardization
✅ TypeScript strict mode

Upgrade Guide

# From v1.x to v2.0
npm install ui-syntheticaia@latest

# Update peer dependencies
npm install react@^19.1.1 react-dom@^19.1.1

Breaking Changes

React 19+ now required
Some prop names updated for consistency
Improved TypeScript definitions

📄 License

MIT License - see LICENSE file for details.

🤝 Support & Community

Getting Help

📖 Documentation: Comprehensive Storybook with examples
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Contributing

We welcome contributions! Please see our contributing guidelines and code of conduct.

Roadmap

Q1 2025: React 19 full optimization, Vite 7.x upgrade
Q2 2025: Tailwind 4.x migration, 100% WCAG compliance
Q3 2025: Advanced AI components, real-time features

🏆 Built by Synthetica Suite

Part of the Synthetica Suite ecosystem - the next generation of enterprise business applications.

Made with ❤️ in Brazil 🇧🇷

ui-syntheticaia