@restnfeel/agentc-starter-kit

# UI Components Documentation This documentation provides comprehensive information about all UI components in the Agent C Starter Kit, including usage examples, props, and best practices. ## Table of Contents - [Button](#button) - [Input](#input) - [Card](#card) - [Modal](#modal) - [Loading](#loading) --- ## Button A versatile button component with multiple variants, sizes, and states. ### Usage ```tsx import { Button } from '@agentc/starter-kit'; // Basic usage <Button>Click me</Button> // With variant and size <Button variant="primary" size="lg"> Large Primary Button </Button> // Loading state <Button loading onClick={handleClick}> Submit </Button> // Disabled state <Button disabled> Disabled Button </Button> ``` ### Props | Prop | Type | Default | Description | | ----------- | -------------------------------------------------------------- | ----------- | ------------------------------- | | `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size | | `disabled` | `boolean` | `false` | Whether the button is disabled | | `loading` | `boolean` | `false` | Whether to show loading spinner | | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type | | `onClick` | `(event: React.MouseEvent<HTMLButtonElement>) => void` | - | Click event handler | | `className` | `string` | `''` | Additional CSS classes | | `children` | `React.ReactNode` | - | Button content | ### Accessibility Props | Prop | Type | Description | | ----------------- | --------- | --------------------------------------- | | `ariaLabel` | `string` | Accessible label for screen readers | | `ariaDescribedBy` | `string` | ID of element that describes the button | | `ariaExpanded` | `boolean` | Whether associated content is expanded | | `ariaPressed` | `boolean` | Pressed state for toggle buttons | ### Variants - **Primary**: Main call-to-action buttons - **Secondary**: Secondary actions - **Outline**: Outlined buttons for less emphasis - **Ghost**: Minimal styling for subtle actions - **Danger**: Destructive actions (delete, remove, etc.) ### Best Practices - Use `primary` variant sparingly for main call-to-action - Always provide meaningful button text or `ariaLabel` - Use `loading` state for async operations - Consider using `ghost` variant for icon-only buttons --- ## Input A flexible input component with support for various types and states. ### Usage ```tsx import { Input } from '@agentc/starter-kit'; // Basic usage <Input placeholder="Enter your name" /> // With label and error <Input label="Email" type="email" error="Please enter a valid email" required /> // Disabled state <Input disabled placeholder="Disabled input" /> ``` ### Props | Prop | Type | Default | Description | | -------------- | ------------------------------------------------------ | -------- | ------------------------------ | | `type` | HTML input types | `'text'` | Input type | | `placeholder` | `string` | - | Placeholder text | | `value` | `string` | - | Controlled value | | `defaultValue` | `string` | - | Default value for uncontrolled | | `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | Change event handler | | `onBlur` | `(event: React.FocusEvent<HTMLInputElement>) => void` | - | Blur event handler | | `onFocus` | `(event: React.FocusEvent<HTMLInputElement>) => void` | - | Focus event handler | | `disabled` | `boolean` | `false` | Whether input is disabled | | `required` | `boolean` | `false` | Whether input is required | | `label` | `string` | - | Input label | | `error` | `string` | - | Error message to display | | `className` | `string` | `''` | Additional CSS classes | ### Best Practices - Always provide accessible labels - Use appropriate input types (`email`, `tel`, `password`, etc.) - Show clear error states with descriptive messages - Consider using placeholder text as hints, not labels --- ## Card A container component for grouping related content with optional header and footer. ### Usage ```tsx import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@agentc/starter-kit'; // Basic usage <Card> <CardContent> Simple card content </CardContent> </Card> // Full structure <Card> <CardHeader> <CardTitle>Card Title</CardTitle> <CardDescription>Card description text</CardDescription> </CardHeader> <CardContent> Main card content goes here </CardContent> <CardFooter> <Button>Action</Button> </CardFooter> </Card> ``` ### Components #### Card Main container component. | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ---------------------- | | `className` | `string` | `''` | Additional CSS classes | | `children` | `React.ReactNode` | - | Card content | #### CardHeader Header section of the card. #### CardTitle Title text for the card header. #### CardDescription Description text for the card header. #### CardContent Main content area of the card. #### CardFooter Footer section for actions or additional info. ### Best Practices - Use semantic structure with proper header/content/footer - Keep card content focused and related - Consider responsive design for different screen sizes --- ## Modal A dialog component for displaying overlay content. ### Usage ```tsx import { Modal, ModalHeader, ModalTitle, ModalDescription, ModalContent, ModalFooter, } from "@agentc/starter-kit"; const [isOpen, setIsOpen] = useState(false); <Modal open={isOpen} onOpenChange={setIsOpen}> <ModalHeader> <ModalTitle>Confirm Action</ModalTitle> <ModalDescription>Are you sure you want to proceed?</ModalDescription> </ModalHeader> <ModalContent>Additional content here</ModalContent> <ModalFooter> <Button variant="outline" onClick={() => setIsOpen(false)}> Cancel </Button> <Button onClick={handleConfirm}>Confirm</Button> </ModalFooter> </Modal>; ``` ### Props #### Modal | Prop | Type | Default | Description | | --------------------- | ------------------------- | ------- | --------------------------------- | | `open` | `boolean` | `false` | Whether modal is open | | `onOpenChange` | `(open: boolean) => void` | - | Called when open state changes | | `closeOnOverlayClick` | `boolean` | `true` | Close modal when clicking overlay | | `closeOnEscape` | `boolean` | `true` | Close modal on Escape key | | `className` | `string` | `''` | Additional CSS classes | | `children` | `React.ReactNode` | - | Modal content | ### Components - **ModalHeader**: Header section with close button - **ModalTitle**: Title for the modal - **ModalDescription**: Description text - **ModalContent**: Main content area - **ModalFooter**: Footer for actions ### Best Practices - Always provide a way to close the modal - Use descriptive titles and descriptions - Focus management for accessibility - Consider mobile responsive design --- ## Loading A loading indicator component with different variants. ### Usage ```tsx import { Loading } from '@agentc/starter-kit'; // Basic spinner <Loading /> // With text <Loading text="Loading..." /> // Different sizes <Loading size="sm" /> <Loading size="lg" /> ``` ### Props | Prop | Type | Default | Description | | ----------- | ---------------------- | ------- | ---------------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Loading indicator size | | `text` | `string` | - | Optional loading text | | `className` | `string` | `''` | Additional CSS classes | ### Best Practices - Use appropriate size for the context - Provide loading text for better user experience - Consider using in buttons or overlays for async operations --- ## General Guidelines ### Accessibility All components follow accessibility best practices: - Proper ARIA attributes - Keyboard navigation support - Screen reader compatibility - Focus management ### Styling Components use Tailwind CSS with design tokens: - Consistent spacing and sizing - Theme-aware colors - Responsive design patterns - Dark mode support ### TypeScript All components are fully typed: - Props interfaces exported - Generic support where applicable - Strict type checking - IntelliSense support ### Testing Components should be tested with: - Unit tests for functionality - Accessibility tests - Visual regression tests - Integration tests