@vkzstudio/muza-ui 1.0.48 → 1.1.0

package/llms-full.md

@@ -1,584 +1,584 @@
-# Muza UI Library Integration
-
-This project uses the `@vkzstudio/muza-ui` component library. Follow these guidelines when working with Muza UI components.
-
-## Quick Reference
-
-```tsx
-// Import styles (required - should already be in main entry file)
-// Alternative: import '@vkzstudio/muza-ui/dist/muza-ui.css'
-// Import components
-import { Alert, Button, Input, Select } from '@vkzstudio/muza-ui'
-import '@vkzstudio/muza-ui/styles'
-```
-
-## MuzaUIProvider
-
-**Required.** Wrap your app root with `MuzaUIProvider` for the library to work correctly. It bundles every context provider the library depends on so you never have to nest them yourself.
-
-```tsx
-import { MuzaUIProvider } from '@vkzstudio/muza-ui'
-
-;<MuzaUIProvider
-  translationConfig={{ locale: 'en' }} // 'en' | 'cs' | 'sk'
-  color="#14645a" // optional white-label brand color
->
-  <App />
-</MuzaUIProvider>
-```
-
-**Bundled providers (do NOT add these again inside your app):**
-
-- `TranslationProvider` — powers locale + translations for DatePicker, Select, Calendar, etc. Configure via `translationConfig`.
-- `TooltipProvider` — already wraps the tree, so `<Tooltip>` works without its own `<TooltipProvider>`. Configure via `tooltipConfig`.
-- `ToastContainer` — mounted automatically, so `toast()` works anywhere with no extra setup. Configure via `toastConfig`.
-- `ThemeProvider` — applies white-label theming when you pass a `color` hex (sets `--brand-*` CSS variables on `:root`).
-
-Components like DatePicker, Select, and Calendar use translated strings automatically. You can override any text via component props.
-
-## Component Usage Rules
-
-### 1. Always Use Library Components
-
-NEVER create new UI components that duplicate Muza UI functionality. Check available components first:
-
-**Complete Component List (57 components)**
-
-**Form & Input (17)**:
-Button, ButtonArrow, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleCheckButton, ToggleGroup, Select, MultiSelect, Searchbar, FileUpload, TextEditor, Slider
-
-**Layout & Structure (7)**:
-Accordion, Card, Flex, Sheet, Typography, Dialog, Skeleton
-
-**Data Display (5)**:
-DataTable, ExpandableTable, Reorderable, ReorderableTable, ResponsiveLayoutTable
-
-**Feedback & Status (9)**:
-Alert, Chip, Tag, Loader, EmptyState, Toast, PinIndicator, SliderIndicators, Progress
-
-**Navigation (9)**:
-Breadcrumb, DropdownMenu, Pagination, SegmentedControl, SegmentedIconControl, Stepper, SwipeButton, EdgeButton, LanguageSwitcher
-
-**Media & Display (4)**:
-Avatar, Carousel, Lightbox, Tooltip
-
-**Date & Time (3)**:
-Calendar, DatePicker, TimePicker
-
-**Specialized (3)**:
-Popover, LoginScreen, Icons
-
-### 2. Component Variants
-
-Use consistent variants across the app:
-
-```tsx
-// Button variants
-variant: "primary" | "secondary" | "tertiary" | "invert" | "dashed" | "link" | "linkInvert"
-size: "xs" | "sm" | "md" | "lg"
-
-// Button modifiers (can combine with any variant)
-ghost: boolean  // Ghost styling overlay
-danger: boolean // Danger styling overlay
-
-// Examples of combinations
-<Button variant="primary" ghost>Ghost Primary</Button>
-<Button variant="secondary" danger>Danger Secondary</Button>
-<Button variant="tertiary" ghost danger>Ghost Danger Tertiary</Button>
-
-// Other Button props
-loading, fullWidth, icon, iconPosition
-
-// Input states
-<Input error={hasError} disabled={isDisabled} />
-<Input mask="(000) 000-0000" placeholder="Phone" /> // With masking
-
-// Alert types (use 'type' not 'variant')
-<Alert type="info" | "success" | "warning" | "error" />
-```
-
-### 3. Design Tokens (Spacing)
-
-Spacing tokens used by Flex `gap`, `p`, `m` props and throughout the library:
-
-| Token  | Value | Token | Value |
-| ------ | ----- | ----- | ----- |
-| `none` | 0px   | `lg`  | 16px  |
-| `3xs`  | 2px   | `xl`  | 20px  |
-| `2xs`  | 4px   | `2xl` | 24px  |
-| `xs`   | 6px   | `3xl` | 32px  |
-| `sm`   | 8px   | `4xl` | 40px  |
-| `md`   | 12px  | `5xl` | 48px  |
-
-```tsx
-// Flex with spacing tokens
-<Flex gap="md" direction="column">  {/* gap = 12px */}
-<Flex gap="lg" p="xl">              {/* gap = 16px, padding = 20px */}
-<Flex gapX="sm" gapY="md">          {/* horizontal gap = 8px, vertical gap = 12px */}
-```
-
-### 4. Compound Components
-
-These components require specific sub-component composition:
-
-#### Dialog (38 uses)
-
-```tsx
-import {
-  Dialog,
-  DialogClose,
-  DialogContent,
-  DialogDescription,
-  DialogTitle,
-  DialogTrigger,
-} from '@vkzstudio/muza-ui'
-
-;<Dialog>
-  <DialogTrigger asChild>
-    <Button>Open Dialog</Button>
-  </DialogTrigger>
-  <DialogContent size="medium">
-    <DialogTitle>Dialog Title</DialogTitle>
-    <DialogDescription>Optional description text.</DialogDescription>
-    {/* Content here */}
-    <DialogClose asChild>
-      <Button variant="secondary">Cancel</Button>
-    </DialogClose>
-  </DialogContent>
-</Dialog>
-```
-
-Sub-components: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`, `DialogOverlay`, `DialogPortal`
-
-#### DropdownMenu (19 uses)
-
-```tsx
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger,
-} from '@vkzstudio/muza-ui'
-
-;<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <Button>Menu</Button>
-  </DropdownMenuTrigger>
-  <DropdownMenuContent>
-    <DropdownMenuItem>Edit</DropdownMenuItem>
-    <DropdownMenuItem>Duplicate</DropdownMenuItem>
-    <DropdownMenuSeparator />
-    <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
-  </DropdownMenuContent>
-</DropdownMenu>
-```
-
-Sub-components: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuPortal`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuButtonItem`
-
-#### Accordion
-
-```tsx
-import {
-  Accordion,
-  AccordionContent,
-  AccordionHeader,
-  AccordionItem,
-} from '@vkzstudio/muza-ui'
-
-;<Accordion type="single" collapsible>
-  <AccordionItem value="item-1">
-    <AccordionHeader>Section 1</AccordionHeader>
-    <AccordionContent>Content for section 1</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
-
-#### Tooltip
-
-`TooltipProvider` is already supplied by `MuzaUIProvider` — do not wrap it again.
-
-```tsx
-import { Tooltip, TooltipContent, TooltipTrigger } from '@vkzstudio/muza-ui'
-
-;<Tooltip>
-  <TooltipTrigger asChild>
-    <Button>Hover me</Button>
-  </TooltipTrigger>
-  <TooltipContent>Tooltip text</TooltipContent>
-</Tooltip>
-```
-
-#### Popover
-
-```tsx
-import { Popover, PopoverContent, PopoverTrigger } from '@vkzstudio/muza-ui'
-
-;<Popover>
-  <PopoverTrigger asChild>
-    <Button>Open</Button>
-  </PopoverTrigger>
-  <PopoverContent>Popover content</PopoverContent>
-</Popover>
-```
-
-### 5. Complex Component APIs
-
-#### DatePicker
-
-DatePicker uses `mode` to determine value/onChange types:
-
-```tsx
-import { DatePicker } from '@vkzstudio/muza-ui'
-import type { DateRange } from 'react-day-picker'
-
-// Single date mode
-const [date, setDate] = useState<Date | undefined>()
-<DatePicker mode="single" value={date} onChange={setDate} />
-
-// Date range mode
-const [dateRange, setDateRange] = useState<DateRange | undefined>()
-<DatePicker mode="range" value={dateRange} onChange={setDateRange} />
-
-// With presets (range mode only)
-<DatePicker
-  mode="range"
-  value={dateRange}
-  onChange={setDateRange}
-  allowedPresets={[
-    { name: 'Last 7 days', type: 'Last 7 days' },
-    { name: 'This month', type: 'This month' },
-    { name: 'Last 30 days', type: 'Last 30 days' },
-  ]}
-/>
-```
-
-#### Select
-
-```tsx
-import { Select } from '@vkzstudio/muza-ui'
-
-;<Select
-  label="Country"
-  options={[
-    { value: 'cz', label: 'Czech Republic' },
-    { value: 'sk', label: 'Slovakia' },
-    { value: 'de', label: 'Germany', disabled: true },
-    { value: 'at', label: 'Austria', icon: <FlagIcon /> },
-  ]}
-  value={selectedCountry}
-  onChange={setSelectedCountry}
-  placeholder="Select a country"
-  error={!!errors.country}
-  hint={errors.country?.message}
-/>
-```
-
-#### toast() (imperative API)
-
-Toast uses an imperative function, not a declarative component:
-
-```tsx
-import { toast } from '@vkzstudio/muza-ui'
-
-// Usage anywhere in your app
-toast({ variant: 'success', text: 'Saved successfully!' })
-toast({ variant: 'error', text: 'Failed to save', closable: true })
-toast({ variant: 'warning', text: 'Unsaved changes', autoDismiss: 5000 })
-```
-
-**Note:** `MuzaUIProvider` already mounts `ToastContainer` — do not add it again. Use `toastConfig` on the provider to customize position/duration. If you are NOT using `MuzaUIProvider` (not recommended), add `<ToastContainer position="top-right" />` to your app root manually.
-
-#### FileUpload
-
-```tsx
-import { FileUpload } from '@vkzstudio/muza-ui'
-
-;<FileUpload
-  onDrop={(acceptedFiles) => handleFiles(acceptedFiles)}
-  accept="image/*"
-  maxSize={5 * 1024 * 1024} // 5MB
-  maxFiles={3}
-  error={!!errors.files}
-  disabled={isSubmitting}
-/>
-```
-
-#### Skeleton
-
-```tsx
-import { Skeleton } from '@vkzstudio/muza-ui'
-
-// Basic skeleton
-<Skeleton className="h-12 w-full" />
-<Skeleton className="h-4 w-3/4" />
-
-// Use color="light" on white backgrounds
-<Skeleton className="h-8 w-32" color="light" />
-
-// ExpandableTable skeleton (static property)
-<Skeleton.ExpandableTable rows={5} />
-```
-
-**Skeleton Loading Pattern:** Attach skeletons as static properties on your components:
-
-```tsx
-const MyComponent = ({ data }: Props) => {
-  return <div>{/* component content */}</div>
-}
-
-const MyComponentSkeleton = () => {
-  return (
-    <Flex gap="md">
-      <Skeleton className="h-12 w-12 rounded-full" />
-      <Skeleton className="h-4 w-3/4" />
-    </Flex>
-  )
-}
-
-MyComponent.Skeleton = MyComponentSkeleton
-export { MyComponent }
-
-// Usage
-{
-  isLoading ? <MyComponent.Skeleton /> : <MyComponent data={data} />
-}
-```
-
-Update skeletons when changing component layout structure, dimensions, or spacing.
-
-### 6. react-hook-form Integration
-
-Most form components integrate with react-hook-form:
-
-```tsx
-import { useForm, Controller } from 'react-hook-form'
-import { Input, Select, DatePicker, Checkbox } from '@vkzstudio/muza-ui'
-
-const { register, control, formState: { errors } } = useForm()
-
-// Input - works with register directly
-<Input
-  {...register('email', { required: 'Email is required' })}
-  label="Email"
-  error={!!errors.email}
-  hint={errors.email?.message as string}
-/>
-
-// Select - use Controller
-<Controller
-  name="country"
-  control={control}
-  rules={{ required: 'Country is required' }}
-  render={({ field }) => (
-    <Select
-      label="Country"
-      options={countries}
-      value={field.value}
-      onChange={field.onChange}
-      error={!!errors.country}
-      hint={errors.country?.message as string}
-    />
-  )}
-/>
-
-// DatePicker - use Controller
-<Controller
-  name="startDate"
-  control={control}
-  render={({ field }) => (
-    <DatePicker
-      mode="single"
-      label="Start Date"
-      value={field.value}
-      onChange={field.onChange}
-      error={!!errors.startDate}
-    />
-  )}
-/>
-
-// Checkbox - use Controller for controlled state
-<Controller
-  name="terms"
-  control={control}
-  rules={{ required: 'You must accept the terms' }}
-  render={({ field }) => (
-    <Checkbox
-      checked={field.value}
-      onCheckedChange={field.onChange}
-      label="I accept the terms"
-    />
-  )}
-/>
-```
-
-### 7. Styling Guidelines
-
-- **DO NOT** recreate Muza UI components with custom CSS
-- **DO** use the `className` prop to add utility classes when needed
-- **DO** use design tokens for custom components that extend Muza UI
-
-```tsx
-// Good - extending with utilities
-<Button className="w-full mt-4" variant="primary">
-  Submit
-</Button>
-
-// Bad - recreating component styles
-<button className="bg-purple-500 hover:bg-purple-600 px-4 py-2 rounded">
-  Submit
-</button>
-```
-
-### 8. Form Patterns
-
-Always use Muza UI form components:
-
-```tsx
-// Good - using library components
-import { Input, Button, Checkbox, Radio } from '@vkzstudio/muza-ui'
-
-function Form() {
-  return (
-    <form>
-      <Input name="email" type="email" required />
-      <Checkbox id="terms" label="I agree to terms" />
-      <Radio value="option1" label="Option 1" />
-      <Button type="submit" variant="primary">
-        Submit
-      </Button>
-    </form>
-  )
-}
-
-// Bad - using native HTML elements
-function Form() {
-  return (
-    <form>
-      <input type="email" />
-      <input type="checkbox" />
-      <button>Submit</button>
-    </form>
-  )
-}
-```
-
-### 9. Icons
-
-Import icons from Muza UI's Icons component (re-exports from `@solar-icons/react-perf`):
-
-```tsx
-import { Button, SearchOutline, TrashBinOutline } from '@vkzstudio/muza-ui'
-
-<Button icon={<SearchOutline />} iconPosition="start">
-  Search
-</Button>
-
-<Button icon={<TrashBinOutline />} danger>
-  Delete
-</Button>
-```
-
-The library also includes custom icons not in Solar Icons (e.g., `XClose`, `ChevronDown`). Check `Icons/CustomIcons` for the full list.
-
-### 10. Accessibility
-
-All Muza UI components include proper ARIA attributes. Maintain accessibility when extending:
-
-```tsx
-<Button aria-label="Save document" aria-busy={isLoading} disabled={isLoading}>
-  {isLoading ? 'Saving...' : 'Save'}
-</Button>
-```
-
-## TypeScript Integration
-
-The library is fully typed. Use the exported types:
-
-```tsx
-import type { ButtonProps, ISelectProps, InputProps } from '@vkzstudio/muza-ui'
-
-interface CustomButtonProps extends ButtonProps {
-  customProp?: boolean
-}
-```
-
-## Performance Guidelines
-
-1. **Import only needed components** - Tree shaking is supported
-2. **Use lazy loading for large components** like Calendar or DatePicker
-3. **Memoize complex forms** when using many Muza UI inputs
-
-## DO NOT
-
-- Create custom Button, Input, or other basic components
-- Use native HTML form elements when Muza UI equivalents exist
-- Override core component styles with !important
-- Mix different UI libraries (Material-UI, Ant Design, etc.) with Muza UI
-- Create custom toast/notification systems
-- Use `<Alert variant="error">` - use `<Alert type="error">` instead
-
-## DO
-
-- Use Muza UI components consistently throughout the app
-- Extend components with className for spacing/layout
-- Follow the established variant patterns
-- Maintain accessibility standards
-- Use Controller from react-hook-form for Select, DatePicker, Checkbox
-- Report any missing components or features needed
-
-## Package Exports
-
-The library supports multiple export paths for flexibility:
-
-```tsx
-// Main components export
-import { Button, Input } from '@vkzstudio/muza-ui'
-
-// Styles
-import '@vkzstudio/muza-ui/styles'
-
-// Individual component exports (tree-shaking friendly)
-import { Button } from '@vkzstudio/muza-ui/components/Button'
-
-// Utilities
-import { cn } from '@vkzstudio/muza-ui/utils'
-
-// Global styles
-import '@vkzstudio/muza-ui/globals.css'
-
-// Third-party library styles (required for components like Lightbox)
-import '@vkzstudio/muza-ui/3rd-parties.css'
-
-// 3D Models (for LoginScreen)
-import modelPath from '@vkzstudio/muza-ui/models/Login3D.glb'
-
-// Individual style tokens (granular imports)
-import '@vkzstudio/muza-ui/styles/token-colors.css'
-import '@vkzstudio/muza-ui/styles/typography.css'
-```
-
-## Troubleshooting
-
-If a component isn't rendering:
-
-1. Check that `@vkzstudio/muza-ui/styles` is imported in your entry file
-2. Verify React 18+ is installed
-3. Ensure all required peer dependencies are installed (see package.json)
-4. Verify the component is properly imported
-5. Check browser console for errors
-6. Ensure Tailwind CSS is properly configured if using custom utilities
-
-**For LoginScreen 3D issues:**
-
-- Ensure the GLB file is copied to `public/models/Login3D.glb`
-- Check that `@react-three/fiber`, `@react-three/drei`, and `three` are installed
-- The 3D scene only renders on desktop (screen width > 1024px)
-
-**For Lightbox image gallery issues:**
-
-- **REQUIRED:** Import third-party styles: `import '@vkzstudio/muza-ui/3rd-parties.css'` in your entry file
-- Check that `photoswipe` and `react-photoswipe-gallery` peer dependencies are installed
-- Ensure images have proper `width` and `height` props for the lightbox to display correctly
-
-Remember: The goal is consistency. Use Muza UI components as designed to maintain a unified design system across the application.
+# Muza UI Library Integration
+
+This project uses the `@vkzstudio/muza-ui` component library. Follow these guidelines when working with Muza UI components.
+
+## Quick Reference
+
+```tsx
+// Import styles (required - should already be in main entry file)
+// Alternative: import '@vkzstudio/muza-ui/dist/muza-ui.css'
+// Import components
+import { Alert, Button, Input, Select } from '@vkzstudio/muza-ui'
+import '@vkzstudio/muza-ui/styles'
+```
+
+## MuzaUIProvider
+
+**Required.** Wrap your app root with `MuzaUIProvider` for the library to work correctly. It bundles every context provider the library depends on so you never have to nest them yourself.
+
+```tsx
+import { MuzaUIProvider } from '@vkzstudio/muza-ui'
+
+;<MuzaUIProvider
+  translationConfig={{ locale: 'en' }} // 'en' | 'cs' | 'sk'
+  color="#14645a" // optional white-label brand color
+>
+  <App />
+</MuzaUIProvider>
+```
+
+**Bundled providers (do NOT add these again inside your app):**
+
+- `TranslationProvider` — powers locale + translations for DatePicker, Select, Calendar, etc. Configure via `translationConfig`.
+- `TooltipProvider` — already wraps the tree, so `<Tooltip>` works without its own `<TooltipProvider>`. Configure via `tooltipConfig`.
+- `ToastContainer` — mounted automatically, so `toast()` works anywhere with no extra setup. Configure via `toastConfig`.
+- `ThemeProvider` — applies white-label theming when you pass a `color` hex (sets `--brand-*` CSS variables on `:root`).
+
+Components like DatePicker, Select, and Calendar use translated strings automatically. You can override any text via component props.
+
+## Component Usage Rules
+
+### 1. Always Use Library Components
+
+NEVER create new UI components that duplicate Muza UI functionality. Check available components first:
+
+**Complete Component List (57 components)**
+
+**Form & Input (17)**:
+Button, ButtonArrow, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleCheckButton, ToggleGroup, Select, MultiSelect, Searchbar, FileUpload, TextEditor, Slider
+
+**Layout & Structure (7)**:
+Accordion, Card, Flex, Sheet, Typography, Dialog, Skeleton
+
+**Data Display (5)**:
+DataTable, ExpandableTable, Reorderable, ReorderableTable, ResponsiveLayoutTable
+
+**Feedback & Status (9)**:
+Alert, Chip, Tag, Loader, EmptyState, Toast, PinIndicator, SliderIndicators, Progress
+
+**Navigation (9)**:
+Breadcrumb, DropdownMenu, Pagination, SegmentedControl, SegmentedIconControl, Stepper, SwipeButton, EdgeButton, LanguageSwitcher
+
+**Media & Display (4)**:
+Avatar, Carousel, Lightbox, Tooltip
+
+**Date & Time (3)**:
+Calendar, DatePicker, TimePicker
+
+**Specialized (3)**:
+Popover, LoginScreen, Icons
+
+### 2. Component Variants
+
+Use consistent variants across the app:
+
+```tsx
+// Button variants
+variant: "primary" | "secondary" | "tertiary" | "invert" | "dashed" | "link" | "linkInvert"
+size: "xs" | "sm" | "md" | "lg"
+
+// Button modifiers (can combine with any variant)
+ghost: boolean  // Ghost styling overlay
+danger: boolean // Danger styling overlay
+
+// Examples of combinations
+<Button variant="primary" ghost>Ghost Primary</Button>
+<Button variant="secondary" danger>Danger Secondary</Button>
+<Button variant="tertiary" ghost danger>Ghost Danger Tertiary</Button>
+
+// Other Button props
+loading, fullWidth, icon, iconPosition
+
+// Input states
+<Input error={hasError} disabled={isDisabled} />
+<Input mask="(000) 000-0000" placeholder="Phone" /> // With masking
+
+// Alert types (use 'type' not 'variant')
+<Alert type="info" | "success" | "warning" | "error" />
+```
+
+### 3. Design Tokens (Spacing)
+
+Spacing tokens used by Flex `gap`, `p`, `m` props and throughout the library:
+
+| Token  | Value | Token | Value |
+| ------ | ----- | ----- | ----- |
+| `none` | 0px   | `lg`  | 16px  |
+| `3xs`  | 2px   | `xl`  | 20px  |
+| `2xs`  | 4px   | `2xl` | 24px  |
+| `xs`   | 6px   | `3xl` | 32px  |
+| `sm`   | 8px   | `4xl` | 40px  |
+| `md`   | 12px  | `5xl` | 48px  |
+
+```tsx
+// Flex with spacing tokens
+<Flex gap="md" direction="column">  {/* gap = 12px */}
+<Flex gap="lg" p="xl">              {/* gap = 16px, padding = 20px */}
+<Flex gapX="sm" gapY="md">          {/* horizontal gap = 8px, vertical gap = 12px */}
+```
+
+### 4. Compound Components
+
+These components require specific sub-component composition:
+
+#### Dialog (38 uses)
+
+```tsx
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+  DialogTrigger,
+} from '@vkzstudio/muza-ui'
+
+;<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent size="medium">
+    <DialogTitle>Dialog Title</DialogTitle>
+    <DialogDescription>Optional description text.</DialogDescription>
+    {/* Content here */}
+    <DialogClose asChild>
+      <Button variant="secondary">Cancel</Button>
+    </DialogClose>
+  </DialogContent>
+</Dialog>
+```
+
+Sub-components: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`, `DialogOverlay`, `DialogPortal`
+
+#### DropdownMenu (19 uses)
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@vkzstudio/muza-ui'
+
+;<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button>Menu</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Edit</DropdownMenuItem>
+    <DropdownMenuItem>Duplicate</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Sub-components: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuPortal`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuButtonItem`
+
+#### Accordion
+
+```tsx
+import {
+  Accordion,
+  AccordionContent,
+  AccordionHeader,
+  AccordionItem,
+} from '@vkzstudio/muza-ui'
+
+;<Accordion type="single" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionHeader>Section 1</AccordionHeader>
+    <AccordionContent>Content for section 1</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+#### Tooltip
+
+`TooltipProvider` is already supplied by `MuzaUIProvider` — do not wrap it again.
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from '@vkzstudio/muza-ui'
+
+;<Tooltip>
+  <TooltipTrigger asChild>
+    <Button>Hover me</Button>
+  </TooltipTrigger>
+  <TooltipContent>Tooltip text</TooltipContent>
+</Tooltip>
+```
+
+#### Popover
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger } from '@vkzstudio/muza-ui'
+
+;<Popover>
+  <PopoverTrigger asChild>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverContent>Popover content</PopoverContent>
+</Popover>
+```
+
+### 5. Complex Component APIs
+
+#### DatePicker
+
+DatePicker uses `mode` to determine value/onChange types:
+
+```tsx
+import { DatePicker } from '@vkzstudio/muza-ui'
+import type { DateRange } from 'react-day-picker'
+
+// Single date mode
+const [date, setDate] = useState<Date | undefined>()
+<DatePicker mode="single" value={date} onChange={setDate} />
+
+// Date range mode
+const [dateRange, setDateRange] = useState<DateRange | undefined>()
+<DatePicker mode="range" value={dateRange} onChange={setDateRange} />
+
+// With presets (range mode only)
+<DatePicker
+  mode="range"
+  value={dateRange}
+  onChange={setDateRange}
+  allowedPresets={[
+    { name: 'Last 7 days', type: 'Last 7 days' },
+    { name: 'This month', type: 'This month' },
+    { name: 'Last 30 days', type: 'Last 30 days' },
+  ]}
+/>
+```
+
+#### Select
+
+```tsx
+import { Select } from '@vkzstudio/muza-ui'
+
+;<Select
+  label="Country"
+  options={[
+    { value: 'cz', label: 'Czech Republic' },
+    { value: 'sk', label: 'Slovakia' },
+    { value: 'de', label: 'Germany', disabled: true },
+    { value: 'at', label: 'Austria', icon: <FlagIcon /> },
+  ]}
+  value={selectedCountry}
+  onChange={setSelectedCountry}
+  placeholder="Select a country"
+  error={!!errors.country}
+  hint={errors.country?.message}
+/>
+```
+
+#### toast() (imperative API)
+
+Toast uses an imperative function, not a declarative component:
+
+```tsx
+import { toast } from '@vkzstudio/muza-ui'
+
+// Usage anywhere in your app
+toast({ variant: 'success', text: 'Saved successfully!' })
+toast({ variant: 'error', text: 'Failed to save', closable: true })
+toast({ variant: 'warning', text: 'Unsaved changes', autoDismiss: 5000 })
+```
+
+**Note:** `MuzaUIProvider` already mounts `ToastContainer` — do not add it again. Use `toastConfig` on the provider to customize position/duration. If you are NOT using `MuzaUIProvider` (not recommended), add `<ToastContainer position="top-right" />` to your app root manually.
+
+#### FileUpload
+
+```tsx
+import { FileUpload } from '@vkzstudio/muza-ui'
+
+;<FileUpload
+  onDrop={(acceptedFiles) => handleFiles(acceptedFiles)}
+  accept="image/*"
+  maxSize={5 * 1024 * 1024} // 5MB
+  maxFiles={3}
+  error={!!errors.files}
+  disabled={isSubmitting}
+/>
+```
+
+#### Skeleton
+
+```tsx
+import { Skeleton } from '@vkzstudio/muza-ui'
+
+// Basic skeleton
+<Skeleton className="h-12 w-full" />
+<Skeleton className="h-4 w-3/4" />
+
+// Use color="light" on white backgrounds
+<Skeleton className="h-8 w-32" color="light" />
+
+// ExpandableTable skeleton (static property)
+<Skeleton.ExpandableTable rows={5} />
+```
+
+**Skeleton Loading Pattern:** Attach skeletons as static properties on your components:
+
+```tsx
+const MyComponent = ({ data }: Props) => {
+  return <div>{/* component content */}</div>
+}
+
+const MyComponentSkeleton = () => {
+  return (
+    <Flex gap="md">
+      <Skeleton className="h-12 w-12 rounded-full" />
+      <Skeleton className="h-4 w-3/4" />
+    </Flex>
+  )
+}
+
+MyComponent.Skeleton = MyComponentSkeleton
+export { MyComponent }
+
+// Usage
+{
+  isLoading ? <MyComponent.Skeleton /> : <MyComponent data={data} />
+}
+```
+
+Update skeletons when changing component layout structure, dimensions, or spacing.
+
+### 6. react-hook-form Integration
+
+Most form components integrate with react-hook-form:
+
+```tsx
+import { useForm, Controller } from 'react-hook-form'
+import { Input, Select, DatePicker, Checkbox } from '@vkzstudio/muza-ui'
+
+const { register, control, formState: { errors } } = useForm()
+
+// Input - works with register directly
+<Input
+  {...register('email', { required: 'Email is required' })}
+  label="Email"
+  error={!!errors.email}
+  hint={errors.email?.message as string}
+/>
+
+// Select - use Controller
+<Controller
+  name="country"
+  control={control}
+  rules={{ required: 'Country is required' }}
+  render={({ field }) => (
+    <Select
+      label="Country"
+      options={countries}
+      value={field.value}
+      onChange={field.onChange}
+      error={!!errors.country}
+      hint={errors.country?.message as string}
+    />
+  )}
+/>
+
+// DatePicker - use Controller
+<Controller
+  name="startDate"
+  control={control}
+  render={({ field }) => (
+    <DatePicker
+      mode="single"
+      label="Start Date"
+      value={field.value}
+      onChange={field.onChange}
+      error={!!errors.startDate}
+    />
+  )}
+/>
+
+// Checkbox - use Controller for controlled state
+<Controller
+  name="terms"
+  control={control}
+  rules={{ required: 'You must accept the terms' }}
+  render={({ field }) => (
+    <Checkbox
+      checked={field.value}
+      onCheckedChange={field.onChange}
+      label="I accept the terms"
+    />
+  )}
+/>
+```
+
+### 7. Styling Guidelines
+
+- **DO NOT** recreate Muza UI components with custom CSS
+- **DO** use the `className` prop to add utility classes when needed
+- **DO** use design tokens for custom components that extend Muza UI
+
+```tsx
+// Good - extending with utilities
+<Button className="w-full mt-4" variant="primary">
+  Submit
+</Button>
+
+// Bad - recreating component styles
+<button className="bg-purple-500 hover:bg-purple-600 px-4 py-2 rounded">
+  Submit
+</button>
+```
+
+### 8. Form Patterns
+
+Always use Muza UI form components:
+
+```tsx
+// Good - using library components
+import { Input, Button, Checkbox, Radio } from '@vkzstudio/muza-ui'
+
+function Form() {
+  return (
+    <form>
+      <Input name="email" type="email" required />
+      <Checkbox id="terms" label="I agree to terms" />
+      <Radio value="option1" label="Option 1" />
+      <Button type="submit" variant="primary">
+        Submit
+      </Button>
+    </form>
+  )
+}
+
+// Bad - using native HTML elements
+function Form() {
+  return (
+    <form>
+      <input type="email" />
+      <input type="checkbox" />
+      <button>Submit</button>
+    </form>
+  )
+}
+```
+
+### 9. Icons
+
+Import icons from Muza UI's Icons component (re-exports from `@solar-icons/react-perf`):
+
+```tsx
+import { Button, SearchOutline, TrashBinOutline } from '@vkzstudio/muza-ui'
+
+<Button icon={<SearchOutline />} iconPosition="start">
+  Search
+</Button>
+
+<Button icon={<TrashBinOutline />} danger>
+  Delete
+</Button>
+```
+
+The library also includes custom icons not in Solar Icons (e.g., `XClose`, `ChevronDown`). Check `Icons/CustomIcons` for the full list.
+
+### 10. Accessibility
+
+All Muza UI components include proper ARIA attributes. Maintain accessibility when extending:
+
+```tsx
+<Button aria-label="Save document" aria-busy={isLoading} disabled={isLoading}>
+  {isLoading ? 'Saving...' : 'Save'}
+</Button>
+```
+
+## TypeScript Integration
+
+The library is fully typed. Use the exported types:
+
+```tsx
+import type { ButtonProps, ISelectProps, InputProps } from '@vkzstudio/muza-ui'
+
+interface CustomButtonProps extends ButtonProps {
+  customProp?: boolean
+}
+```
+
+## Performance Guidelines
+
+1. **Import only needed components** - Tree shaking is supported
+2. **Use lazy loading for large components** like Calendar or DatePicker
+3. **Memoize complex forms** when using many Muza UI inputs
+
+## DO NOT
+
+- Create custom Button, Input, or other basic components
+- Use native HTML form elements when Muza UI equivalents exist
+- Override core component styles with !important
+- Mix different UI libraries (Material-UI, Ant Design, etc.) with Muza UI
+- Create custom toast/notification systems
+- Use `<Alert variant="error">` - use `<Alert type="error">` instead
+
+## DO
+
+- Use Muza UI components consistently throughout the app
+- Extend components with className for spacing/layout
+- Follow the established variant patterns
+- Maintain accessibility standards
+- Use Controller from react-hook-form for Select, DatePicker, Checkbox
+- Report any missing components or features needed
+
+## Package Exports
+
+The library supports multiple export paths for flexibility:
+
+```tsx
+// Main components export
+import { Button, Input } from '@vkzstudio/muza-ui'
+
+// Styles
+import '@vkzstudio/muza-ui/styles'
+
+// Individual component exports (tree-shaking friendly)
+import { Button } from '@vkzstudio/muza-ui/components/Button'
+
+// Utilities
+import { cn } from '@vkzstudio/muza-ui/utils'
+
+// Global styles
+import '@vkzstudio/muza-ui/globals.css'
+
+// Third-party library styles (required for components like Lightbox)
+import '@vkzstudio/muza-ui/3rd-parties.css'
+
+// 3D Models (for LoginScreen)
+import modelPath from '@vkzstudio/muza-ui/models/Login3D.glb'
+
+// Individual style tokens (granular imports)
+import '@vkzstudio/muza-ui/styles/token-colors.css'
+import '@vkzstudio/muza-ui/styles/typography.css'
+```
+
+## Troubleshooting
+
+If a component isn't rendering:
+
+1. Check that `@vkzstudio/muza-ui/styles` is imported in your entry file
+2. Verify React 18+ is installed
+3. Ensure all required peer dependencies are installed (see package.json)
+4. Verify the component is properly imported
+5. Check browser console for errors
+6. Ensure Tailwind CSS is properly configured if using custom utilities
+
+**For LoginScreen 3D issues:**
+
+- Ensure the GLB file is copied to `public/models/Login3D.glb`
+- Check that `@react-three/fiber`, `@react-three/drei`, and `three` are installed
+- The 3D scene only renders on desktop (screen width > 1024px)
+
+**For Lightbox image gallery issues:**
+
+- **REQUIRED:** Import third-party styles: `import '@vkzstudio/muza-ui/3rd-parties.css'` in your entry file
+- Check that `photoswipe` and `react-photoswipe-gallery` peer dependencies are installed
+- Ensure images have proper `width` and `height` props for the lightbox to display correctly
+
+Remember: The goal is consistency. Use Muza UI components as designed to maintain a unified design system across the application.