@luxury-presence/design-system-ui

@luxury-presence/design-system-ui

The core UI component library for the Luxury Presence Design System. This package provides a comprehensive set of React components with TypeScript support, built for both web and React Native applications.

Features

• Comprehensive Component Library: Buttons, forms, data tables, navigation, and more
• TypeScript Support: Full type safety with comprehensive TypeScript definitions
• Dual Format Builds: ES modules and CommonJS for maximum compatibility
• Tree-Shakable: Individual component exports for optimal bundle sizes
• Storybook Integration: Interactive component development and testing
• Design System Integration: Built with design tokens and system icons
• Accessibility First: WCAG compliant components with proper ARIA support
• Modern Tooling: Built with Vite, tested with Vitest

Installation

# npm
npm install @luxury-presence/design-system-ui

# yarn
yarn add @luxury-presence/design-system-ui

# pnpm
pnpm add @luxury-presence/design-system-ui

Peer Dependencies

This package requires several peer dependencies to be installed in your project:

pnpm add react react-dom @luxury-presence/design-system-tokens @luxury-presence/design-system-icons tailwindcss

Optional peer dependencies (only needed for specific components):

# For data tables
pnpm add @tanstack/react-table @tanstack/react-virtual

# For GraphQL-powered select components
pnpm add @apollo/client

# For drag-and-drop functionality
pnpm add @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

# For advanced UI interactions
pnpm add @floating-ui/react vaul input-otp react-day-picker react-resizable-panels

Usage

Basic Component Usage

import { Button, Input, Card } from '@luxury-presence/design-system-ui';

function MyComponent() {
  return (
    <Card>
      <Card.Header>
        <Card.Title>Example Form</Card.Title>
      </Card.Header>
      <Card.Content>
        <Input placeholder="Enter your name" />
        <Button>Submit</Button>
      </Card.Content>
    </Card>
  );
}

Individual Component Imports

For better tree-shaking, import components individually:

import { Button } from '@luxury-presence/design-system-ui/components/button';
import { Input } from '@luxury-presence/design-system-ui/components/input';
import { Card } from '@luxury-presence/design-system-ui/components/card';

Data Table Usage

The data table is available as a specialized export:

import { DataTable } from '@luxury-presence/design-system-ui/data-table';

function MyTableComponent() {
  return (
    <DataTable
      columns={columns}
      data={data}
      features={{
        search: true,
        pagination: true,
        bulkActions: true,
      }}
    />
  );
}

Styling with CSS

Import the component styles in your application:

@import '@luxury-presence/design-system-ui/styles';

Component Categories

Core UI Components

Layout & Structure

• Card - Flexible container with header, content, and footer sections
• Separator - Visual dividers and spacing elements
• Resizable - Resizable panel containers

Form Controls

• Button - Primary, secondary, and variant button styles
• Input - Text inputs with validation states
• Textarea - Multi-line text input
• Checkbox - Single and group checkbox controls
• RadioGroup - Radio button selections
• Select - Dropdown selection with search and multi-select
• Label - Form field labels with proper associations

Navigation

• Breadcrumb - Navigation breadcrumb trails
• Menubar - Top-level navigation menu
• NavigationMenu - Multi-level navigation structure
• Sidebar - Collapsible side navigation
• Tabs - Tab-based content switching

Data Display

• Avatar - User profile images and placeholders
• Badge - Status indicators and labels
• Table - Basic data table with sorting
• Skeleton - Loading state placeholders

Feedback & Overlays

• Dialog - Modal dialogs and confirmations
• Sheet - Side panel overlays
• Tooltip - Contextual help and information
• Loader - Loading spinners and progress indicators

Interactive Elements

• Command - Command palette and search interface
• ContextMenu - Right-click context menus
• DropdownMenu - Action menus and dropdowns
• Popover - Floating content containers
• Carousel - Image and content carousels

Specialized Components

Advanced Data Components

• DataTable - Feature-rich table with search, filtering, pagination, and bulk actions
• Pagination - Standalone pagination controls

Domain-Specific Selectors

• SelectBrokerage - Brokerage selection with GraphQL integration
• SelectMLSProvider - MLS provider selection
• SelectTemplate - Template selection interface
• SelectUser - User selection with search

Utility Components

• IconButton - Buttons with integrated icons
• Chip - Removable tags and filters
• Banner - Alert banners and notifications
• SegmentedPicker - Toggle-style option selection

Development

Prerequisites

• Node.js 22.x or higher
• pnpm 8.x or higher

Development Setup

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Start Storybook
pnpm storybook

# Run tests
pnpm test

# Build library
pnpm build

Project Structure

src/
├── components/
│   ├── ui/                    # Core UI components
│   │   ├── button/
│   │   │   ├── index.tsx     # Component implementation
│   │   │   └── button.stories.tsx # Storybook stories
│   │   └── [other components]/
│   ├── data-table/           # Advanced data table system
│   │   ├── index.tsx        # Main data table component
│   │   ├── features/        # Feature modules
│   │   └── [table parts]/   # Sub-components
│   └── select-*/            # Domain-specific selectors
├── hooks/                   # Custom React hooks
├── lib/                     # Utility functions
├── types/                   # TypeScript type definitions
└── index.ts                # Main entry point

Adding New Components

• Create component directory: src/components/ui/my-component/
• Implement component: index.tsx with proper TypeScript types
• Add Storybook stories: my-component.stories.tsx
• Export from main index: Add to src/index.ts
• Build and test: pnpm build && pnpm test

GraphQL Integration

Some components use GraphQL for dynamic data loading. To use these features:

• Configure Apollo Client in your application
• Provide GraphQL endpoints for data fetching
• Set up code generation: pnpm codegen to generate types

Build System

Dual Format Output

The package builds both ES modules and CommonJS:

• ES Modules: dist/es/ - Modern module format
• CommonJS: dist/cjs/ - Legacy compatibility
• Types: dist/ - TypeScript declarations

Bundle Optimization

• Tree-shaking: Individual component exports
• Module preservation: Granular import paths
• External dependencies: Peer dependencies are externalized
• CSS handling: Single optimized CSS bundle

Build Commands

pnpm build          # Full production build
pnpm build:lib      # Library build only (alias)
pnpm generate:exports # Generate explicit exports for optimization

Testing

pnpm test           # Run unit tests
pnpm test:watch     # Watch mode testing
pnpm storybook      # Visual testing with Storybook

The package uses:

• Vitest for unit testing
• React Testing Library for component testing
• Storybook for visual and interaction testing
• TypeScript for type safety validation

Contributing

• Follow existing patterns for component structure and naming
• Include TypeScript types for all props and exports
• Add Storybook stories for new components
• Write tests for component behavior
• Update exports in index files for discoverability

Code Standards

• TypeScript strict mode enforced
• ESLint rules for code quality
• Prettier formatting for consistency
• Accessibility standards (WCAG compliance)

Version History

This package follows semantic versioning. See CHANGELOG.md for detailed release notes.

License

This package is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.

© 2025 Luxury Presence. All rights reserved.