@dbs-portal/core-ui

Shared UI components and design system for DBS Portal, built on top of Ant Design with custom theming and enhanced functionality. Now includes advanced integrations with TanStack Form, Framer Motion, Floating UI, and Headless UI for comprehensive UI capabilities.

Features

• 🎨 Ant Design Integration - Built on top of Ant Design with custom theming
• 🎭 Enhanced Icons - Comprehensive icon system with @ant-design/icons
• 📝 Advanced Forms - TanStack Form integration for powerful form management
• ✨ Smooth Animations - Framer Motion components for beautiful animations
• 🎯 Smart Positioning - Floating UI for advanced tooltip and popover positioning
• ♿ Accessibility First - Headless UI components for maximum accessibility
• 🎨 Design System - Consistent design tokens and theming
• 📱 Responsive - Mobile-first responsive design
• 🔧 TypeScript - Full TypeScript support with comprehensive types

Installation

yarn add @dbs-portal/core-ui

Peer Dependencies

The package requires these peer dependencies:

yarn add react react-dom antd @ant-design/icons @tanstack/react-form framer-motion @floating-ui/react @headlessui/react

Usage

Basic Setup

import React from 'react'
import { ThemeProvider, Button, Input, Card } from '@dbs-portal/core-ui'

function App() {
  return (
    <ThemeProvider>
      <div>
        <Button variant="primary">Click me</Button>
        <Input placeholder="Enter text" />
        <Card title="Example Card">
          <p>Card content goes here</p>
        </Card>
      </div>
    </ThemeProvider>
  )
}

Enhanced Features Setup

import React from 'react'
import {
  ThemeProvider,
  Button,
  FadeIn,
  FloatingTooltip,
  AccessibleDialog,
  Form,
  FormField
} from '@dbs-portal/core-ui'

function EnhancedApp() {
  return (
    <ThemeProvider>
      <FadeIn duration="normal">
        <FloatingTooltip content="This is a tooltip">
          <Button variant="primary">Hover me</Button>
        </FloatingTooltip>

        <Form onSubmit={(data) => console.log(data)}>
          <FormField
            name="email"
            label="Email"
            component="input"
            validators={[required(), email()]}
          />
          <Button type="submit">Submit</Button>
        </Form>
      </FadeIn>
    </ThemeProvider>
  )
}

Components

Button

A customizable button component with multiple variants and sizes.

import { Button } from '@dbs-portal/core-ui'

// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>
<Button variant="danger">Danger</Button>

// Sizes
<Button size="xs">Extra Small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra Large</Button>

// With icons
<Button icon={<Icon />}>With Icon</Button>
<Button icon={<Icon />} iconPosition="end">Icon at End</Button>

// States
<Button loading>Loading</Button>
<Button disabled>Disabled</Button>
<Button block>Block Button</Button>

Input

Enhanced input component with support for prefixes, suffixes, and various states.

import { Input, TextArea } from '@dbs-portal/core-ui'

// Basic input
<Input placeholder="Enter text" />

// With prefix/suffix
<Input prefix="$" suffix=".00" />

// Different sizes
<Input size="sm" />
<Input size="md" />
<Input size="lg" />

// With status
<Input status="error" />
<Input status="warning" />

// TextArea
<TextArea rows={4} placeholder="Enter description" />

Card

Flexible card component for displaying content.

import { Card } from '@dbs-portal/core-ui'

// Basic card
<Card title="Card Title">
  <p>Card content</p>
</Card>

// With extra actions
<Card 
  title="Card Title" 
  extra={<Button>Action</Button>}
  actions={[<Button key="1">Edit</Button>, <Button key="2">Delete</Button>]}
>
  <p>Card content</p>
</Card>

// With cover image
<Card cover={<img src="image.jpg" alt="Cover" />}>
  <Card.Meta title="Title" description="Description" />
</Card>

Modal

Accessible modal component with focus management.

import { Modal } from '@dbs-portal/core-ui'

function MyComponent() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open Modal</Button>
      <Modal
        open={open}
        title="Modal Title"
        onCancel={() => setOpen(false)}
        onOk={() => setOpen(false)}
      >
        <p>Modal content</p>
      </Modal>
    </>
  )
}

Layout

Layout components for structuring your application.

import { Layout } from '@dbs-portal/core-ui'

const { Header, Content, Footer, Sider } = Layout

function AppLayout() {
  return (
    <Layout>
      <Header>Header content</Header>
      <Layout hasSider>
        <Sider>Sidebar content</Sider>
        <Content>Main content</Content>
      </Layout>
      <Footer>Footer content</Footer>
    </Layout>
  )
}

Form

Enhanced form components with better styling and validation.

import { Form, Input, Button } from '@dbs-portal/core-ui'

function MyForm() {
  const [form] = Form.useForm()

  return (
    <Form form={form} layout="vertical">
      <Form.Item label="Name" name="name" required>
        <Input placeholder="Enter your name" />
      </Form.Item>
      <Form.Item>
        <Button htmlType="submit">Submit</Button>
      </Form.Item>
    </Form>
  )
}

Hooks

useTheme

Access theme context and utilities.

import { useTheme } from '@dbs-portal/core-ui'

function MyComponent() {
  const { mode, setMode, isDark, toggleTheme } = useTheme()
  
  return (
    <Button onClick={toggleTheme}>
      Switch to {isDark ? 'light' : 'dark'} mode
    </Button>
  )
}

useResponsive

Handle responsive behavior in components.

import { useBreakpoint, useIsMobile } from '@dbs-portal/core-ui'

function ResponsiveComponent() {
  const breakpoint = useBreakpoint()
  const isMobile = useIsMobile()
  
  return (
    <div>
      Current breakpoint: {breakpoint}
      {isMobile && <p>Mobile view</p>}
    </div>
  )
}

Enhanced Modules

Icons (@dbs-portal/core-ui/icons)

Enhanced icon system with theming and animation support:

import { Icon, IconButton, IconText } from '@dbs-portal/core-ui/icons'
import { UserOutlined } from '@ant-design/icons'

// Enhanced icon with theming
<Icon
  icon={UserOutlined}
  size="lg"
  color="primary"
  animation="spin"
/>

// Icon button with tooltip
<IconButton
  icon={UserOutlined}
  tooltip="User Profile"
  onClick={() => {}}
/>

// Icon with text
<IconText icon={UserOutlined} placement="start">
  User Profile
</IconText>

Animations (@dbs-portal/core-ui/animations)

Framer Motion integration for smooth animations:

import { FadeIn, SlideIn, ScaleIn, Stagger } from '@dbs-portal/core-ui/animations'

// Fade in animation
<FadeIn duration="normal" delay={0.2}>
  <div>Content</div>
</FadeIn>

// Slide in from different directions
<SlideIn direction="up" distance={20}>
  <Card>Sliding content</Card>
</SlideIn>

// Stagger children animations
<Stagger staggerDelay={0.1}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stagger>

Positioning (@dbs-portal/core-ui/positioning)

Advanced positioning with Floating UI:

import {
  FloatingTooltip,
  FloatingDropdown,
  FloatingPopover
} from '@dbs-portal/core-ui/positioning'

// Advanced tooltip
<FloatingTooltip
  content="Advanced tooltip"
  placement="top"
  arrow={true}
>
  <Button>Hover me</Button>
</FloatingTooltip>

// Dropdown with smart positioning
<FloatingDropdown
  trigger={<Button>Open Menu</Button>}
  placement="bottom-start"
>
  <Menu>
    <Menu.Item>Option 1</Menu.Item>
    <Menu.Item>Option 2</Menu.Item>
  </Menu>
</FloatingDropdown>

Accessibility (@dbs-portal/core-ui/accessibility)

Headless UI components for maximum accessibility:

import {
  AccessibleDialog,
  AccessibleSwitch,
  AccessibleTabs
} from '@dbs-portal/core-ui/accessibility'

// Accessible dialog
<AccessibleDialog
  open={isOpen}
  onClose={setIsOpen}
  title="Dialog Title"
>
  <p>Dialog content</p>
</AccessibleDialog>

// Accessible switch
<AccessibleSwitch
  checked={enabled}
  onChange={setEnabled}
  label="Enable notifications"
  description="Receive email notifications"
/>

Forms (@dbs-portal/core-ui/forms/tanstack)

TanStack Form integration:

import {
  Form,
  FormField,
  useEnhancedForm,
  useFieldValidation
} from '@dbs-portal/core-ui/forms/tanstack'

function MyForm() {
  const { required, email } = useFieldValidation()

  return (
    <Form onSubmit={(data) => console.log(data)}>
      <FormField
        name="email"
        label="Email Address"
        component="input"
        validators={[required(), email()]}
      />
      <FormField
        name="message"
        label="Message"
        component="textarea"
        validators={[required()]}
      />
      <Button type="submit">Submit</Button>
    </Form>
  )
}

Customization

Theme Customization

The components use the theme system from @dbs-portal/core-theme. You can customize colors, typography, spacing, and more through design tokens.

CSS Classes

All components include CSS classes for custom styling:

• .dbs-button - Button component
• .dbs-input - Input component
• .dbs-card - Card component
• .dbs-modal - Modal component
• .dbs-layout - Layout components

TypeScript Support

All components are fully typed with TypeScript, providing excellent developer experience with IntelliSense and type checking.

Accessibility

Components follow accessibility best practices:

• Proper ARIA attributes
• Keyboard navigation support
• Focus management
• Screen reader compatibility

Dependencies

Core Dependencies

• React 19+
• Ant Design 5.26+
• @dbs-portal/core-theme
• @dbs-portal/core-shared

Enhanced Dependencies

• @tanstack/react-form - Advanced form management
• framer-motion - Smooth animations and transitions
• @floating-ui/react - Smart positioning for tooltips and popovers
• @headlessui/react - Accessible, unstyled UI components

Migration Guide

From Previous Versions

The enhanced UI package maintains backward compatibility with existing components. New features are available through separate imports:

// Existing components (unchanged)
import { Button, Input, Card } from '@dbs-portal/core-ui'

// New enhanced modules (opt-in)
import { FadeIn } from '@dbs-portal/core-ui/animations'
import { FloatingTooltip } from '@dbs-portal/core-ui/positioning'
import { AccessibleDialog } from '@dbs-portal/core-ui/accessibility'

Performance Considerations

Enhanced modules are tree-shakeable and only loaded when imported:

// Only loads animation utilities
import { FadeIn, SlideIn } from '@dbs-portal/core-ui/animations'

// Only loads positioning utilities
import { FloatingTooltip } from '@dbs-portal/core-ui/positioning'

Contributing

When contributing to the enhanced UI package:

1. Follow established patterns - Use existing component structures
2. Maintain backward compatibility - Don't break existing APIs
3. Add comprehensive tests - Test both functionality and accessibility
4. Update documentation - Include examples and usage guides
5. Consider performance - Ensure tree-shaking and lazy loading work correctly

License

MIT