@epic-flow/flowstate-ui

Shared UI components for FlowState applications, built on shadcn/ui.

Overview

@epic-flow/flowstate-ui provides a comprehensive library of reusable React components based on shadcn/ui. These components are designed to be used across all FlowState applications, ensuring consistent UI/UX while maintaining flexibility and customization.

Features

• Modern React Components: Built with React 19 and TypeScript
• Tailwind CSS: Styled with Tailwind CSS utilities
• shadcn/ui Base: Leverages the popular shadcn/ui component library
• Accessible: Built with accessibility in mind using Radix UI primitives
• Customizable: Easy to theme and customize
• Type-Safe: Full TypeScript support with comprehensive type definitions
• Tree-Shakeable: Only import the components you need
• Dual Module Format: Supports both ESM and CommonJS

Installation

This package is part of the Epic Flow monorepo and is meant to be used as a workspace dependency:

# Add to your app's package.json dependencies
yarn workspace @epic-flow/your-app add @epic-flow/flowstate-ui

Or add directly to your package.json:

{
  "dependencies": {
    "@epic-flow/flowstate-ui": "workspace:*"
  }
}

Peer Dependencies

This package requires the following peer dependencies:

{
  "react": "19.1.0",
  "react-dom": "19.1.0",
  "lucide-react": "^0.263.1"
}

Make sure these are installed in your consuming application.

Usage

Basic Import

import { Button, Card, Input } from '@epic-flow/flowstate-ui';

function MyComponent() {
  return (
    <Card>
      <Input placeholder="Enter text..." />
      <Button>Submit</Button>
    </Card>
  );
}

Using Utilities

import { cn } from '@epic-flow/flowstate-ui';

function MyComponent({ className }: { className?: string }) {
  return (
    <div className={cn('base-class', className)}>
      Content
    </div>
  );
}

Using Hooks

import { useToast } from '@epic-flow/flowstate-ui';

function MyComponent() {
  const { toast } = useToast();

  const handleClick = () => {
    toast({
      title: "Success",
      description: "Operation completed successfully",
    });
  };

  return <button onClick={handleClick}>Show Toast</button>;
}

Available Components

All components are fully typed with TypeScript and accessible via named exports.

Layout Components

• Card - Container component with header, content, and footer sections
• Separator - Visual or semantic separator between content sections
• Sheet - Slide-out panel component (drawer/sidebar)
• Tabs - Tabbed interface component
• Collapsible - Expandable/collapsible content sections
• ScrollArea - Custom scrollable area with styled scrollbars

Form Components

• Button - Customizable button with multiple variants and sizes
• Input - Text input field
• Label - Form label component
• Textarea - Multi-line text input
• Select - Dropdown select component
• RadioGroup - Radio button group for single selection

Feedback Components

• Toast - Toast notification system
• Toaster - Toast container and manager
• Dialog - Modal dialog component
• Avatar - User avatar with image and fallback
• Badge - Small status or label badge

Navigation Components

• DropdownMenu - Dropdown menu with items, checkboxes, and radio groups
• Tooltip - Contextual tooltip on hover

Data Display Components

• Table - Table component with header, body, row, and cell components

Utilities

cn(...inputs: ClassValue[]): string

A utility function that combines clsx and tailwind-merge for intelligent class name merging:

cn('px-4 py-2', 'bg-blue-500', { 'text-white': true })
// Result: 'px-4 py-2 bg-blue-500 text-white'

// Handles Tailwind conflicts intelligently
cn('px-2', 'px-4') // Result: 'px-4' (last value wins)

Hooks

useToast()

A hook for managing toast notifications in your application. Returns methods to show, update, and dismiss toasts.

import { useToast } from '@epic-flow/flowstate-ui';

function MyComponent() {
  const { toast, dismiss } = useToast();

  const showNotification = () => {
    const { id } = toast({
      title: "Notification",
      description: "This is a toast message",
    });

    // Dismiss after 3 seconds
    setTimeout(() => dismiss(id), 3000);
  };

  return <button onClick={showNotification}>Show Toast</button>;
}

Styling

This package uses Tailwind CSS for styling. Ensure your consuming application has Tailwind CSS configured with the following:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@epic-flow/flowstate-ui/dist/**/*.{js,mjs}',
  ],
  // ... rest of config
};

Development

Building

# Build the package
yarn workspace @epic-flow/flowstate-ui build

# Watch mode for development
yarn workspace @epic-flow/flowstate-ui dev

Testing

# Run tests
yarn workspace @epic-flow/flowstate-ui test

# Watch mode
yarn workspace @epic-flow/flowstate-ui test:watch

# Coverage report
yarn workspace @epic-flow/flowstate-ui test:coverage

Linting

# Check for linting issues
yarn workspace @epic-flow/flowstate-ui lint

# Fix linting issues automatically
yarn workspace @epic-flow/flowstate-ui lint:fix

Type Checking

yarn workspace @epic-flow/flowstate-ui typecheck

Project Structure

packages/flowstate-ui/
├── src/
│   ├── components/
│   │   └── ui/              # shadcn/ui components
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       ├── input.tsx
│   │       └── index.ts
│   ├── hooks/               # Custom React hooks
│   │   ├── use-toast.ts
│   │   └── index.ts
│   ├── lib/                 # Utility functions
│   │   └── utils.ts
│   └── index.ts             # Main entry point
├── dist/                    # Built output (generated)
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

Adding New Components

When adding new components from shadcn/ui or creating custom components:

1. Add the component source file to src/components/ui/
2. Export the component from src/components/ui/index.ts
3. Update the "Available Components" section in this README
4. Add tests if applicable
5. Rebuild the package

Example:

// src/components/ui/button.tsx
export function Button({ children, ...props }) {
  return <button {...props}>{children}</button>;
}

// src/components/ui/index.ts
export { Button } from './button';

Contributing

Guidelines

1. Follow shadcn/ui Patterns: When adding components, maintain consistency with shadcn/ui design patterns
2. Type Safety: All components must have proper TypeScript types
3. Accessibility: Ensure components meet WCAG 2.1 AA standards
4. Documentation: Update README and add JSDoc comments for public APIs
5. Testing: Add tests for new components and functionality

Component Checklist

• [ ] Component source file created in src/components/ui/
• [ ] TypeScript types properly defined
• [ ] Exported from src/components/ui/index.ts
• [ ] Props interface documented with JSDoc
• [ ] Accessibility requirements met
• [ ] README updated with component info
• [ ] Tests added (if applicable)
• [ ] Package builds successfully
• [ ] Tested in consuming application

Architecture Decisions

Why shadcn/ui?

shadcn/ui was chosen for several reasons:

1. Copy, Don't Install: Components are copied into your codebase, giving full control
2. Customizable: Easy to modify and extend components
3. Accessible: Built on Radix UI primitives with excellent accessibility
4. Modern Stack: Uses React 19, TypeScript, and Tailwind CSS
5. Well-Maintained: Active community and regular updates

Package Structure

• Dual Module Format: Both ESM and CJS for maximum compatibility
• Peer Dependencies: React and lucide-react are peer dependencies to avoid duplication
• Barrel Exports: Clean imports through index files
• Type Definitions: Generated .d.ts files for full TypeScript support

Troubleshooting

Build Issues

Problem: TypeScript errors during build

# Clean and rebuild
yarn workspace @epic-flow/flowstate-ui clean
yarn workspace @epic-flow/flowstate-ui build

Problem: Missing peer dependencies

# Install peer dependencies in your consuming app
yarn add [email protected] [email protected] lucide-react@^0.263.1

Import Issues

Problem: Components not found

Make sure you've built the package:

yarn workspace @epic-flow/flowstate-ui build

Problem: Type definitions not working

Ensure your tsconfig.json includes the package:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@epic-flow/flowstate-ui": ["node_modules/@epic-flow/flowstate-ui"]
    }
  }
}

License

MIT

Author

Epic Digital Interactive Media LLC

Links

• Repository
• Issues
• shadcn/ui Documentation
• Radix UI Documentation