@vkzstudio/muza-ui 1.0.11 → 1.0.13

package/dist/styles/token-sizes.css

@@ -81,6 +81,7 @@
   --spacing-comp-carousel-circle-size: var(--spacing-28);
   --spacing-comp-checkbox-w-stroke: var(--spacing-1);
   --spacing-comp-dialog-p-hor: var(--spacing-2xl);
+  --spacing-comp-dialog-p-hor-sm: var(--spacing-xl);
   --spacing-comp-dialog-p: var(--spacing-3xl);
   --spacing-comp-dialog-gap: var(--spacing-4xl);
   --spacing-comp-dialog-p-hor-overlay: var(--spacing-5xl);
@@ -250,6 +251,7 @@
     --spacing-comp-carousel-circle-size: var(--spacing-28);
     --spacing-comp-checkbox-w-stroke: var(--spacing-1);
     --spacing-comp-dialog-p-hor: var(--spacing-2xl);
+    --spacing-comp-dialog-p-hor-sm: var(--spacing-xl);
     --spacing-comp-dialog-p: var(--spacing-3xl);
     --spacing-comp-dialog-gap: var(--spacing-4xl);
     --spacing-comp-dialog-p-hor-overlay: var(--spacing-5xl);
@@ -423,6 +425,7 @@
     --spacing-comp-dialog-p: var(--spacing-xl);
     --spacing-comp-dialog-p-hor-overlay: var(--spacing-xl);
     --spacing-comp-dialog-p-hor: var(--spacing-2xl);
+    --spacing-comp-dialog-p-hor-sm: var(--spacing-xl);
     --spacing-comp-dialog-gap: var(--spacing-3xl);
     --spacing-comp-dialog-img-h: var(--spacing-56);
     --spacing-comp-dialog-img-w: 100px;
@@ -592,6 +595,7 @@
     --spacing-comp-carousel-circle-size: var(--spacing-28);
     --spacing-comp-checkbox-w-stroke: var(--spacing-1);
     --spacing-comp-dialog-p-hor: var(--spacing-2xl);
+    --spacing-comp-dialog-p-hor-sm: var(--spacing-xl);
     --spacing-comp-dialog-p: var(--spacing-3xl);
     --spacing-comp-dialog-gap: var(--spacing-4xl);
     --spacing-comp-dialog-p-hor-overlay: var(--spacing-5xl);

package/llms-full.md

@@ -0,0 +1,581 @@
+# 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
+
+Wrap your app with `MuzaUIProvider` to enable translations and built-in `ToastContainer`:
+
+```tsx
+import { MuzaUIProvider } from '@vkzstudio/muza-ui'
+
+;<MuzaUIProvider locale="en">
+  {' '}
+  {/* 'en' | 'cs' | 'sk' */}
+  <App />
+</MuzaUIProvider>
+```
+
+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 (48 components)**
+
+**Form & Input (14)**:
+Button, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleGroup, Select, MultiSelect, Searchbar, FileUpload, TextEditor
+
+**Layout & Structure (5)**:
+Accordion, Flex, Typography, Dialog, Skeleton
+
+**Data Display (4)**:
+DataTable, ExpandableTable, Reorderable, ReorderableTable
+
+**Feedback & Status (8)**:
+Alert, Chip, Tag, Loader, EmptyState, Toast, PinIndicator, SliderIndicators
+
+**Navigation (8)**:
+Breadcrumb, DropdownMenu, SegmentedControl, SegmentedIconControl, Stepper, SwipeButton, EdgeButton, LanguageSwitcher
+
+**Media & Display (3)**:
+Avatar, 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`, `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`, `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
+
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@vkzstudio/muza-ui'
+
+;<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button>Hover me</Button>
+    </TooltipTrigger>
+    <TooltipContent>Tooltip text</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+#### 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:** If using `MuzaUIProvider`, `ToastContainer` is already included. Otherwise, add `<ToastContainer position="top-right" />` to your app root.
+
+#### 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.

package/llms.txt

@@ -0,0 +1,36 @@
+# Muza UI
+
+> React component library (48 components) built with Tailwind CSS 4, shadcn/ui patterns, and Radix primitives. Provides form inputs, layout components, feedback indicators, navigation, and date/time pickers.
+
+## Documentation
+
+- [llms-full.md](llms-full.md): Integration guide with usage rules, compound component patterns, and react-hook-form examples
+- [dist/index.d.ts](dist/index.d.ts): TypeScript definitions with JSDoc on all props
+
+## Quick Start
+
+```tsx
+import { MuzaUIProvider, Button, Input } from '@vkzstudio/muza-ui'
+import '@vkzstudio/muza-ui/styles'
+
+<MuzaUIProvider locale="en">
+  <App />
+</MuzaUIProvider>
+```
+
+See llms-full.md for component APIs, compound component patterns, and react-hook-form integration.
+
+## Component Categories (48 total)
+
+**Form & Input (14)**: Button, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleGroup, Select, MultiSelect, Searchbar, FileUpload, TextEditor
+**Layout (5)**: Accordion, Flex, Typography, Dialog, Skeleton
+**Data Display (4)**: DataTable, ExpandableTable, Reorderable, ReorderableTable
+**Feedback (8)**: Alert, Chip, Tag, Loader, EmptyState, Toast, PinIndicator, SliderIndicators
+**Navigation (8)**: Breadcrumb, DropdownMenu, SegmentedControl, SegmentedIconControl, Stepper, SwipeButton, EdgeButton, LanguageSwitcher
+**Media (3)**: Avatar, Lightbox, Tooltip
+**Date/Time (3)**: Calendar, DatePicker, TimePicker
+**Specialized (3)**: Popover, LoginScreen, Icons
+
+## Optional
+
+- [Storybook](https://muza-ui.vercel.app): Visual component examples with live demos

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vkzstudio/muza-ui",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "React component library built with Vite, shadcn/ui, and Tailwind CSS",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,8 @@
   ],
   "files": [
     "dist",
-    "CLAUDE_CONSUMER.md"
+    "llms-full.md",
+    "llms.txt"
   ],
   "scripts": {
     "dev": "storybook dev -p 6006",
@@ -48,7 +49,7 @@
     "add-component:win": "powershell -ExecutionPolicy Bypass -File scripts/add-component.ps1",
     "format": "prettier --write .",
     "chromatic": "npx chromatic --project-token=chpt_23ce248b589dbff",
-    "local-publish": "npm run build && npx shx rm -rf ../internal-benefits-frontend/node_modules/@vkzstudio/muza-ui/dist && npx shx cp -r dist ../internal-benefits-frontend/node_modules/@vkzstudio/muza-ui/dist"
+    "local-publish": "npm run build && npx shx rm -rf ../internal-benefits-frontend/node_modules/@vkzstudio/muza-ui/dist && npx shx cp -r dist ../internal-benefits-frontend/node_modules/@vkzstudio/muza-ui/dist && npx shx cp llms.txt llms-full.md ../internal-benefits-frontend/node_modules/@vkzstudio/muza-ui/"
   },
   "dependencies": {
     "react-day-picker": "^9.9.0",