@vkzstudio/muza-ui 1.0.3 → 1.0.4

package/CLAUDE_CONSUMER.md

@@ -1,238 +1,238 @@
-# 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'
-```
-
-## 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 (42 components)**
-
-**Form & Input Components (13)**:
-Button, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleGroup, Select, MultiSelect, Searchbar, FileUpload
-
-**Layout & Structure (5)**:
-Accordion, Flex, Typography, Dialog, ExpandableTable
-
-**Feedback & Status (7)**:
-Alert, Tag, Loader, EmptyState, Snackbar, 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. 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>
-```
-
-### 4. 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>
-  )
-}
-```
-
-### 5. Icons
-
-Use Muza UI icons from the Solar Icons integration:
-
-```tsx
-import { Button } from '@vkzstudio/muza-ui'
-
-// Icons are integrated with @solar-icons/react-perf
-// Import from Solar Icons directly in your project
-// Muza UI components support icon props where applicable
-
-;<Button icon={<SearchIcon />} iconPosition="start">
-  Search
-</Button>
-```
-
-### 7. 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, 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
-
-## DO
-
-- Use Muza UI components consistently throughout the app
-- Extend components with className for spacing/layout
-- Follow the established variant patterns
-- Maintain accessibility standards
-- 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'
+```
+
+## 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 (42 components)**
+
+**Form & Input Components (13)**:
+Button, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleGroup, Select, MultiSelect, Searchbar, FileUpload
+
+**Layout & Structure (5)**:
+Accordion, Flex, Typography, Dialog, ExpandableTable
+
+**Feedback & Status (7)**:
+Alert, Tag, Loader, EmptyState, Snackbar, 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. 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>
+```
+
+### 4. 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>
+  )
+}
+```
+
+### 5. Icons
+
+Use Muza UI icons from the Solar Icons integration:
+
+```tsx
+import { Button } from '@vkzstudio/muza-ui'
+
+// Icons are integrated with @solar-icons/react-perf
+// Import from Solar Icons directly in your project
+// Muza UI components support icon props where applicable
+
+;<Button icon={<SearchIcon />} iconPosition="start">
+  Search
+</Button>
+```
+
+### 7. 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, 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
+
+## DO
+
+- Use Muza UI components consistently throughout the app
+- Extend components with className for spacing/layout
+- Follow the established variant patterns
+- Maintain accessibility standards
+- 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.