@adlas/create-app 1.0.0

package/templates/docs/UI_COMPONENTS_GUIDE.md

@@ -0,0 +1,893 @@
+# UI Components Guide
+
+Complete reference for all available UI components in the Berndorf e-commerce project. All components are based on **HeroUI** and extended for project-specific needs.
+
+## Table of Contents
+
+1. [Form Components](#form-components)
+2. [Display Components](#display-components)
+3. [Form System](#form-system)
+4. [Element Components](#element-components)
+5. [Component Usage Patterns](#component-usage-patterns)
+
+---
+
+## Form Components
+
+### Input
+
+Text input field with label placement outside by default.
+
+**Location:** `/src/components/ui/Input.tsx`
+
+**Props:**
+- `label` - Field label (string)
+- `placeholder` - Placeholder text (string)
+- `isInvalid` - Invalid state (boolean)
+- `errorMessage` - Error message (string)
+- `isDisabled` - Disabled state (boolean)
+- `value` - Input value (string)
+- `onChange` - Change handler (function)
+
+**Variants:**
+- `variant`: `bordered` (default)
+- `size`: `sm`, `md`, `lg` (default)
+- `labelPlacement`: `outside` (default), `inside`
+- `radius`: `none` (default), `sm`, `md`, `lg`, `full`
+
+**Example:**
+```tsx
+import { Input } from '@/components/ui/Input';
+
+<Input
+  label="Email Address"
+  placeholder="Enter your email"
+  type="email"
+  isRequired
+/>
+```
+
+---
+
+### PasswordInput
+
+Password field with show/hide toggle.
+
+**Location:** `/src/components/ui/PasswordInput.tsx`
+
+**Props:** Same as Input, plus:
+- Automatically includes visibility toggle icon
+
+**Example:**
+```tsx
+import { PasswordInput } from '@/components/ui/PasswordInput';
+
+<PasswordInput
+  label="Password"
+  placeholder="Enter your password"
+  isRequired
+/>
+```
+
+---
+
+### Textarea
+
+Multi-line text input.
+
+**Location:** `/src/components/ui/Textarea.tsx`
+
+**Props:**
+- All Input props, plus:
+- `rows` - Number of rows (number)
+- `minRows` - Minimum rows (number)
+- `maxRows` - Maximum rows (number)
+
+**Example:**
+```tsx
+import { Textarea } from '@/components/ui/Textarea';
+
+<Textarea
+  label="Message"
+  placeholder="Enter your message"
+  minRows={3}
+  maxRows={10}
+/>
+```
+
+---
+
+### Select
+
+Dropdown selection component.
+
+**Location:** `/src/components/ui/Select.tsx`
+
+**Props:**
+- `label` - Field label (string)
+- `placeholder` - Placeholder text (string)
+- `items` - Array of options (SelectItem[])
+- `selectedKey` - Selected value (string)
+- `onSelectionChange` - Selection change handler (function)
+
+**Example:**
+```tsx
+import { Select, SelectItem } from '@/components/ui/Select';
+
+const options = [
+  { key: 'option1', label: 'Option 1' },
+  { key: 'option2', label: 'Option 2' },
+];
+
+<Select
+  label="Choose option"
+  placeholder="Select an option"
+>
+  {options.map((option) => (
+    <SelectItem key={option.key}>{option.label}</SelectItem>
+  ))}
+</Select>
+```
+
+---
+
+### Autocomplete
+
+Searchable dropdown with filtering.
+
+**Location:** `/src/components/ui/Autocomplete.tsx`
+
+**Props:**
+- `label` - Field label (string)
+- `placeholder` - Placeholder text (string)
+- `items` - Array of options (AutocompleteItem[])
+- `onSelectionChange` - Selection change handler (function)
+
+**Example:**
+```tsx
+import { Autocomplete, AutocompleteItem } from '@/components/ui/Autocomplete';
+
+const items = [
+  { id: '1', label: 'Apple' },
+  { id: '2', label: 'Banana' },
+];
+
+<Autocomplete
+  label="Search fruits"
+  placeholder="Type to search"
+  items={items}
+>
+  {(item) => <AutocompleteItem key={item.id}>{item.label}</AutocompleteItem>}
+</Autocomplete>
+```
+
+---
+
+### Checkbox
+
+Single checkbox component.
+
+**Location:** `/src/components/ui/Checkbox.tsx`
+
+**Props:**
+- `children` - Checkbox label (ReactNode)
+- `isSelected` - Checked state (boolean)
+- `onValueChange` - Change handler (function)
+- `isDisabled` - Disabled state (boolean)
+
+**Example:**
+```tsx
+import { Checkbox } from '@/components/ui/Checkbox';
+
+<Checkbox isSelected={agreed} onValueChange={setAgreed}>
+  I agree to the terms and conditions
+</Checkbox>
+```
+
+---
+
+### RadioGroup
+
+Radio button group.
+
+**Location:** `/src/components/ui/RadioGroup.tsx`
+
+**Props:**
+- `label` - Group label (string)
+- `value` - Selected value (string)
+- `onValueChange` - Change handler (function)
+- `children` - Radio buttons (RadioButton components)
+
+**Example:**
+```tsx
+import { RadioGroup, Radio } from '@/components/ui/RadioGroup';
+
+<RadioGroup
+  label="Select delivery method"
+  value={deliveryMethod}
+  onValueChange={setDeliveryMethod}
+>
+  <Radio value="standard">Standard Delivery</Radio>
+  <Radio value="express">Express Delivery</Radio>
+</RadioGroup>
+```
+
+---
+
+### NumberInput
+
+Numeric input with increment/decrement buttons.
+
+**Location:** `/src/components/ui/NumberInput.tsx`
+
+**Props:**
+- `label` - Field label (string)
+- `value` - Numeric value (number)
+- `onChange` - Change handler (function)
+- `min` - Minimum value (number)
+- `max` - Maximum value (number)
+- `step` - Increment step (number)
+
+**Example:**
+```tsx
+import { NumberInput } from '@/components/ui/NumberInput';
+
+<NumberInput
+  label="Quantity"
+  value={quantity}
+  onChange={setQuantity}
+  min={1}
+  max={100}
+  step={1}
+/>
+```
+
+---
+
+### FileInput
+
+File upload input.
+
+**Location:** `/src/components/ui/FileInput.tsx`
+
+**Props:**
+- `label` - Field label (string)
+- `accept` - Accepted file types (string)
+- `onChange` - Change handler (function)
+- `multiple` - Allow multiple files (boolean)
+
+**Example:**
+```tsx
+import { FileInput } from '@/components/ui/FileInput';
+
+<FileInput
+  label="Upload document"
+  accept=".pdf,.doc,.docx"
+  onChange={handleFileChange}
+/>
+```
+
+---
+
+### DocumentUpload
+
+Advanced document upload with validation.
+
+**Location:** `/src/components/ui/DocumentUpload.tsx`
+
+**Props:**
+- `label` - Field label (string)
+- `accept` - Accepted file types (string)
+- `maxSize` - Maximum file size in bytes (number)
+- `onUpload` - Upload handler (function)
+
+**Example:**
+```tsx
+import { DocumentUpload } from '@/components/ui/DocumentUpload';
+
+<DocumentUpload
+  label="Upload PDF"
+  accept=".pdf"
+  maxSize={5 * 1024 * 1024} // 5MB
+  onUpload={handleUpload}
+/>
+```
+
+---
+
+### DatePicker
+
+Date selection component.
+
+**Location:** `/src/components/ui/DatePicker.tsx`
+
+**Props:**
+- `label` - Field label (string)
+- `value` - Date value (DateValue)
+- `onChange` - Change handler (function)
+- `minValue` - Minimum date (DateValue)
+- `maxValue` - Maximum date (DateValue)
+
+**Example:**
+```tsx
+import { DatePicker } from '@/components/ui/DatePicker';
+import { parseDate } from '@internationalized/date';
+
+<DatePicker
+  label="Select date"
+  value={date}
+  onChange={setDate}
+  minValue={parseDate('2024-01-01')}
+/>
+```
+
+---
+
+## Display Components
+
+### Button
+
+Action button with multiple variants.
+
+**Location:** `/src/components/ui/Button.tsx`
+
+**Props:**
+- `children` - Button content (ReactNode)
+- `onPress` - Click handler (function)
+- `isDisabled` - Disabled state (boolean)
+- `isLoading` - Loading state (boolean)
+- `variant` - Visual variant (string)
+- `color` - Color theme (string)
+- `size` - Button size (string)
+
+**Variants:**
+- `variant`: `solid` (default), `bordered`, `light`, `flat`, `faded`, `shadow`, `ghost`, `primary`
+- `color`: `primary` (default), `secondary`, `success`, `warning`, `danger`, `default`, `foreground`
+- `size`: `sm`, `md` (default), `lg`
+- `radius`: `none` (default), `sm`, `md`, `lg`, `full`
+
+**Example:**
+```tsx
+import { Button } from '@/components/ui/Button';
+
+// Primary solid button
+<Button variant="solid" color="primary">
+  Submit
+</Button>
+
+// Bordered button
+<Button variant="bordered">
+  Cancel
+</Button>
+
+// Light button with danger color
+<Button variant="light" color="danger">
+  Delete
+</Button>
+
+// Loading state
+<Button isLoading>
+  Processing...
+</Button>
+```
+
+---
+
+### Chip
+
+Small badge or tag component.
+
+**Location:** `/src/components/ui/Chip.tsx`
+
+**Props:**
+- `children` - Chip content (ReactNode)
+- `variant` - Visual variant (string)
+- `color` - Color theme (string)
+- `size` - Chip size (string)
+
+**Variants:**
+- `variant`: `solid`, `bordered`, `flat`, `shadow`
+- `color`: `primary`, `secondary`, `success`, `warning`, `danger`, `default`
+- `size`: `sm`, `md`, `lg`
+
+**Example:**
+```tsx
+import { Chip } from '@/components/ui/Chip';
+
+<Chip color="success" variant="flat">
+  New
+</Chip>
+
+<Chip color="primary">
+  Featured
+</Chip>
+```
+
+---
+
+### Modal
+
+Dialog/popup component.
+
+**Location:** `/src/components/ui/Modal.tsx`
+
+**Props:**
+- `isOpen` - Modal open state (boolean)
+- `onClose` - Close handler (function)
+- `title` - Modal title (string)
+- `children` - Modal content (ReactNode)
+- `size` - Modal size (string)
+
+**Sizes:**
+- `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`, `full`
+
+**Example:**
+```tsx
+import { Modal, ModalContent, ModalHeader, ModalBody, ModalFooter } from '@/components/ui/Modal';
+import { Button } from '@/components/ui/Button';
+
+<Modal isOpen={isOpen} onClose={onClose} size="lg">
+  <ModalContent>
+    <ModalHeader>
+      <h2>Confirm Action</h2>
+    </ModalHeader>
+    <ModalBody>
+      <p>Are you sure you want to proceed?</p>
+    </ModalBody>
+    <ModalFooter>
+      <Button variant="light" onPress={onClose}>
+        Cancel
+      </Button>
+      <Button color="primary" onPress={handleConfirm}>
+        Confirm
+      </Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+```
+
+---
+
+### Tabs
+
+Tab navigation component.
+
+**Location:** `/src/components/ui/Tabs.tsx`
+
+**Props:**
+- `selectedKey` - Active tab key (string)
+- `onSelectionChange` - Tab change handler (function)
+- `children` - Tab items (TabItem components)
+
+**Example:**
+```tsx
+import { Tabs, Tab } from '@/components/ui/Tabs';
+
+<Tabs selectedKey={activeTab} onSelectionChange={setActiveTab}>
+  <Tab key="details" title="Details">
+    <div>Details content</div>
+  </Tab>
+  <Tab key="specs" title="Specifications">
+    <div>Specifications content</div>
+  </Tab>
+</Tabs>
+```
+
+---
+
+### Breadcrumbs
+
+Breadcrumb navigation.
+
+**Location:** `/src/components/ui/Breadcrumbs.tsx`
+
+**Props:**
+- `items` - Breadcrumb items (BreadcrumbItem[])
+
+**Example:**
+```tsx
+import { Breadcrumbs, BreadcrumbItem } from '@/components/ui/Breadcrumbs';
+
+<Breadcrumbs>
+  <BreadcrumbItem href="/">Home</BreadcrumbItem>
+  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
+  <BreadcrumbItem>Current Page</BreadcrumbItem>
+</Breadcrumbs>
+```
+
+---
+
+### Carousel
+
+Image/content carousel.
+
+**Location:** `/src/components/ui/Carousel.tsx`
+
+**Props:**
+- `items` - Carousel items (array)
+- `autoplay` - Auto-play slides (boolean)
+- `interval` - Auto-play interval in ms (number)
+
+**Example:**
+```tsx
+import { Carousel } from '@/components/ui/Carousel';
+
+const slides = [
+  { id: 1, image: '/slide1.jpg', title: 'Slide 1' },
+  { id: 2, image: '/slide2.jpg', title: 'Slide 2' },
+];
+
+<Carousel items={slides} autoplay interval={5000} />
+```
+
+---
+
+### Icon
+
+Icon component.
+
+**Location:** `/src/components/ui/Icon.tsx`
+
+**Props:**
+- `name` - Icon name (string)
+- `size` - Icon size (number or string)
+- `color` - Icon color (string)
+
+**Example:**
+```tsx
+import { Icon } from '@/components/ui/Icon';
+
+<Icon name="heart" size={24} color="primary" />
+```
+
+---
+
+## Form System
+
+### Form
+
+Form wrapper with validation support.
+
+**Location:** `/src/components/ui/form/Form.tsx`
+
+**Props:**
+- `form` - react-hook-form instance (UseFormReturn)
+- `validationSchema` - Zod validation schema (ZodSchema)
+- `children` - Form fields (ReactNode)
+- `className` - Additional classes (string)
+
+**Example:**
+```tsx
+import { Form } from '@/components/ui/form/Form';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+type FormData = z.infer<typeof schema>;
+
+function MyForm() {
+  const form = useForm<FormData>();
+
+  return (
+    <Form form={form} validationSchema={schema}>
+      {/* Form fields */}
+    </Form>
+  );
+}
+```
+
+---
+
+### FormItem
+
+Individual form field wrapper with error handling.
+
+**Location:** `/src/components/ui/form/Form.tsx`
+
+**Props:**
+- `name` - Field name (string, must match schema)
+- `children` - Render function for input component (function)
+- `rowsNumber` - Grid column span (1 or 2)
+- `extraLabel` - Additional label above field (string)
+
+**Example:**
+```tsx
+import { Form } from '@/components/ui/form/Form';
+import { Input } from '@/components/ui/Input';
+
+<Form.Item name="email">
+  {(props) => <Input {...props} label="Email Address" type="email" />}
+</Form.Item>
+
+<Form.Item name="description" rowsNumber={1}>
+  {(props) => <Textarea {...props} label="Description" />}
+</Form.Item>
+```
+
+---
+
+### FormGenerator
+
+Dynamic form generation from schema.
+
+**Location:** `/src/components/ui/form/FormGenerator.tsx`
+
+**Props:**
+- `schema` - Form schema definition (object)
+- `onSubmit` - Form submit handler (function)
+
+**Example:**
+```tsx
+import { FormGenerator } from '@/components/ui/form/FormGenerator';
+
+const formSchema = {
+  fields: [
+    { name: 'email', type: 'email', label: 'Email' },
+    { name: 'password', type: 'password', label: 'Password' },
+  ],
+};
+
+<FormGenerator schema={formSchema} onSubmit={handleSubmit} />
+```
+
+---
+
+## Element Components
+
+Higher-level composite components built from UI components.
+
+### ProductCard
+
+Product display card.
+
+**Location:** `/src/components/elements/ProductCard.tsx`
+
+**Usage:**
+```tsx
+import { ProductCard } from '@/components/elements/ProductCard';
+
+<ProductCard
+  id={product.id}
+  name={product.name}
+  price={product.price}
+  image={product.image}
+  onAddToCart={handleAddToCart}
+/>
+```
+
+---
+
+### NewsCard
+
+News article card.
+
+**Location:** `/src/components/elements/NewsCard.tsx`
+
+**Usage:**
+```tsx
+import { NewsCard } from '@/components/elements/NewsCard';
+
+<NewsCard
+  title={news.title}
+  excerpt={news.excerpt}
+  image={news.image}
+  date={news.date}
+  href={`/news/${news.slug}`}
+/>
+```
+
+---
+
+### CollectionCard
+
+Collection display card.
+
+**Location:** `/src/components/elements/CollectionCard.tsx`
+
+**Usage:**
+```tsx
+import { CollectionCard } from '@/components/elements/CollectionCard';
+
+<CollectionCard
+  name={collection.name}
+  image={collection.image}
+  itemCount={collection.itemCount}
+  href={`/collections/${collection.slug}`}
+/>
+```
+
+---
+
+### Gallery
+
+Image gallery component.
+
+**Location:** `/src/components/elements/Gallery.tsx`
+
+**Usage:**
+```tsx
+import { Gallery } from '@/components/elements/Gallery';
+
+<Gallery
+  images={product.images}
+  title={product.name}
+/>
+```
+
+---
+
+### EmptyState
+
+Empty state placeholder.
+
+**Location:** `/src/components/elements/EmptyState.tsx`
+
+**Usage:**
+```tsx
+import { EmptyState } from '@/components/elements/EmptyState';
+
+<EmptyState
+  title="No items found"
+  description="Try adjusting your filters"
+  icon="search"
+/>
+```
+
+---
+
+### ContactCard
+
+Contact information card.
+
+**Location:** `/src/components/elements/ContactCard.tsx`
+
+**Usage:**
+```tsx
+import { ContactCard } from '@/components/elements/ContactCard';
+
+<ContactCard
+  name="Support"
+  email="support@example.com"
+  phone="+43 123 456 789"
+/>
+```
+
+---
+
+### StoreCard
+
+Store location card.
+
+**Location:** `/src/components/elements/StoreCard.tsx`
+
+**Usage:**
+```tsx
+import { StoreCard } from '@/components/elements/StoreCard';
+
+<StoreCard
+  name={store.name}
+  address={store.address}
+  phone={store.phone}
+  hours={store.hours}
+/>
+```
+
+---
+
+### HeaderBanner
+
+Page header banner.
+
+**Location:** `/src/components/elements/HeaderBanner.tsx`
+
+**Usage:**
+```tsx
+import { HeaderBanner } from '@/components/elements/HeaderBanner';
+
+<HeaderBanner
+  title="Our Products"
+  description="Explore our premium cutlery collection"
+  image="/banners/products.jpg"
+/>
+```
+
+---
+
+## Component Usage Patterns
+
+### 1. Form Field with Validation
+
+```tsx
+<Form.Item name="email">
+  {(props) => (
+    <Input
+      {...props}
+      label="Email Address"
+      type="email"
+      placeholder="your@email.com"
+      isRequired
+    />
+  )}
+</Form.Item>
+```
+
+### 2. Conditional Button State
+
+```tsx
+<Button
+  variant="solid"
+  color="primary"
+  isLoading={isSubmitting}
+  isDisabled={!isValid}
+  onPress={handleSubmit}
+>
+  {isSubmitting ? 'Submitting...' : 'Submit'}
+</Button>
+```
+
+### 3. Modal with Form
+
+```tsx
+<Modal isOpen={isOpen} onClose={onClose}>
+  <ModalContent>
+    <ModalHeader>Add New Item</ModalHeader>
+    <ModalBody>
+      <Form form={form} validationSchema={schema}>
+        <Form.Item name="name">
+          {(props) => <Input {...props} label="Name" />}
+        </Form.Item>
+      </Form>
+    </ModalBody>
+    <ModalFooter>
+      <Button variant="light" onPress={onClose}>Cancel</Button>
+      <Button onPress={form.handleSubmit(onSubmit)}>Save</Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+```
+
+### 4. Responsive Grid Layout
+
+```tsx
+<div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
+  {products.map((product) => (
+    <ProductCard key={product.id} {...product} />
+  ))}
+</div>
+```
+
+### 5. Loading State
+
+```tsx
+{isLoading ? (
+  <div className="flex justify-center items-center h-64">
+    <Spinner size="lg" />
+  </div>
+) : (
+  <div>{/* Content */}</div>
+)}
+```
+
+---
+
+## Best Practices
+
+1. **Always use existing components** - Never create custom UI components if HeroUI provides them
+2. **Spread props correctly** - Use `{...props}` in FormItem children for proper validation
+3. **Type your forms** - Always infer form types from Zod schemas: `type FormData = z.infer<typeof schema>`
+4. **Use translations** - Never hardcode text, always use `useTranslations()`
+5. **Handle loading states** - Always show loading indicators for async operations
+6. **Validate user input** - Use Zod schemas for all form validation
+7. **Maintain consistency** - Use the same variants and sizes across similar components
+8. **Test responsiveness** - Ensure components work on all screen sizes
+
+## Need More Information?
+
+- **Quick Reference** → See `AI_QUICK_REFERENCE.md`
+- **Architecture Patterns** → See `ARCHITECTURE_PATTERNS.md`
+- **Implementation Guide** → See `IMPLEMENTATION_GUIDE.md`
+- **Figma to Code** → See `FIGMA_TO_CODE_GUIDE.md`