@vkzstudio/muza-ui 1.5.2 → 1.6.0

package/llms-full.md

@@ -44,8 +44,8 @@ NEVER create new UI components that duplicate Muza UI functionality. Check avail
 
 **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
+**Form & Input (18)**:
+Button, ButtonArrow, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleCheckButton, ToggleGroup, Select, SelectTrigger, MultiSelect, Searchbar, FileUpload, TextEditor, Slider
 
 **Layout & Structure (7)**:
 Accordion, Card, Flex, Sheet, Typography, Dialog, Skeleton
@@ -176,6 +176,25 @@ import {
 
 Sub-components: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuPortal`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuButtonItem`
 
+**Navigation entries must be links.** Use `asChild` on `DropdownMenuItem` so the item
+renders as a real anchor instead of a div with an `onSelect` handler:
+
+```tsx
+<DropdownMenuItem asChild icon={<HeartBold />}>
+  <Link href="/profile/favorite">Favorites</Link>
+</DropdownMenuItem>
+```
+
+This produces a single `<a role="menuitem">` carrying the item styling, with the icon
+inside it. Do NOT use `onSelect={() => router.push('/x')}` for navigation — it throws
+away middle-click, Ctrl+click, "open link in new tab", "copy link address", the hover
+URL preview, link semantics for screen readers and framework prefetching.
+
+`icon`, `isActive` and `description` all still render, and keyboard navigation,
+typeahead and `onSelect` are unchanged. `asChild` works the same way on
+`DropdownMenuCheckboxItem` and `DropdownMenuRadioItem`, though a navigating child makes
+little sense for those.
+
 #### Accordion
 
 ```tsx
@@ -222,6 +241,69 @@ import { Popover, PopoverContent, PopoverTrigger } from '@vkzstudio/muza-ui'
 </Popover>
 ```
 
+#### Carousel
+
+Built on [Embla Carousel](https://www.embla-carousel.com/). `CarouselItem` is full-width by default — override `basis-*` for multi-slide layouts.
+
+```tsx
+import {
+  Carousel,
+  CarouselContent,
+  CarouselDots,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+} from '@vkzstudio/muza-ui'
+
+;<Carousel align="start" options={{ loop: true }}>
+  <CarouselContent>
+    <CarouselItem className="basis-1/2 md:basis-1/3">Slide 1</CarouselItem>
+    <CarouselItem className="basis-1/2 md:basis-1/3">Slide 2</CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+  <CarouselDots />
+</Carousel>
+```
+
+**Autoplay** — set `autoplay` for a self-running carousel. Do NOT install `embla-carousel-autoplay` or hand-roll a timer in your app; the library owns this.
+
+```tsx
+// Advances every 5000ms by default; pair with loop for a seamless wrap
+<Carousel autoplay options={{ loop: true }}>...</Carousel>
+
+// Custom interval
+<Carousel autoplay autoplayDelay={3000}>...</Carousel>
+```
+
+- Pauses on hover (mouse only) and while dragging; resumes on mouse leave, once the slide settles, or after a plain tap.
+- Never runs under `prefers-reduced-motion: reduce`, or with a single slide.
+- `autoplay` appends Embla's `Autoplay` plugin to `plugins`, so your own plugins keep working. Passing your own `Autoplay({ ... })` instance via `plugins` takes precedence — `autoplay` steps aside rather than adding a second timer.
+
+**Custom controls** — `useCarousel()` exposes the carousel's state and controls to any descendant, so you don't need `setApi` + local state for a counter, progress bar, or bespoke dot strip. It throws outside a `<Carousel>`.
+
+```tsx
+import { useCarousel } from '@vkzstudio/muza-ui'
+
+const SlideCounter = () => {
+  const { selectedIndex, slidesCount } = useCarousel()
+  return (
+    <span>
+      {selectedIndex + 1} / {slidesCount}
+    </span>
+  )
+}
+
+;<Carousel>
+  <CarouselContent>...</CarouselContent>
+  <SlideCounter /> {/* must be inside <Carousel> */}
+</Carousel>
+```
+
+Returns `api`, `carouselRef`, `scrollPrev`, `scrollNext`, `scrollTo(index)`, `canScrollPrev`, `canScrollNext`, `selectedIndex`, `slidesCount`, plus the root's `options` / `orientation` / `plugins`.
+
+Other props: `orientation` (`'horizontal' | 'vertical'`), `align`, `options` (Embla options), `plugins` (Embla plugins), `setApi` (imperative Embla API).
+
 ### 5. Complex Component APIs
 
 #### DatePicker
@@ -274,6 +356,53 @@ import { Select } from '@vkzstudio/muza-ui'
 />
 ```
 
+#### SelectTrigger (styling a menu trigger)
+
+`Select` is a value picker with combobox/listbox semantics. When the design calls for
+the select pill but the control is really a **menu** — an account dropdown, a filter
+menu, a navigation dropdown — use `SelectTrigger`, the exact button `Select` renders,
+exported on its own. Do not hand-copy the `comp-select-*` tokens into your own
+`<button>`; that silently drifts whenever Select is restyled.
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  SelectTrigger,
+} from '@vkzstudio/muza-ui'
+
+;<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <SelectTrigger size="sm" className="max-w-comp-market-nav-select-max-w">
+      {userName}
+    </SelectTrigger>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end" sideOffset={8}>
+    <DropdownMenuItem icon={<UserBold />}>My profile</DropdownMenuItem>
+    <DropdownMenuItem icon={<Logout2Outline />}>Log out</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Key points:
+
+- **Stateless — no `open` prop.** The expanded border and the chevron rotation come
+  from `data-state="open"`, which Radix sets on the trigger in `Select`,
+  `DropdownMenu`, `Popover` and friends. Do not keep a local `menuOpen` state for
+  styling.
+- **`asChild` works.** It is a `forwardRef` over a single `<button>` and spreads every
+  remaining prop, so Radix's ref, handlers, `aria-expanded`, `aria-haspopup` and
+  `data-state` all land on it.
+- **It owns the chevron and truncation.** A `string` or `number` child is rendered in
+  the standard truncated label style; pass a node for full control.
+- `className` is merged with `cn`, so `max-w-*` and friends work.
+- Props: `size` (`'xs' | 'sm' | 'base' | 'lg'`), `error`, `disabled`, `prefix`,
+  `hasDescription`, plus all native `<button>` attributes.
+- `triggerWrapperVariants` is also exported as an escape hatch for cases that cannot
+  use the component, but prefer the component.
+
 #### toast() (imperative API)
 
 Toast uses an imperative function, not a declarative component:
@@ -517,6 +646,8 @@ interface CustomButtonProps extends ButtonProps {
 - 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
+- Copy `comp-select-*` classes into your own trigger button - use `SelectTrigger`
+- Use `<Select>` for a menu of actions - it is a combobox; use `SelectTrigger` inside `DropdownMenuTrigger asChild`
 
 ## DO
 

package/llms.txt

@@ -21,6 +21,8 @@ import '@vkzstudio/muza-ui/styles'
 
 See llms-full.md for component APIs, compound component patterns, and react-hook-form integration.
 
+Some components own behaviour you should not re-implement in an app — e.g. `Carousel` has built-in autoplay (`autoplay` / `autoplayDelay`, with hover/drag pausing and `prefers-reduced-motion` support), so don't install `embla-carousel-autoplay` or hand-roll a timer.
+
 ## Component Categories (57 total)
 
 **Form & Input (17)**: Button, ButtonArrow, Input, PasswordInput, Textarea, Checkbox, Radio, Switch, Toggle, ToggleCheckButton, ToggleGroup, Select, MultiSelect, Searchbar, FileUpload, TextEditor, Slider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vkzstudio/muza-ui",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "React component library built with Vite, shadcn/ui, and Tailwind CSS",
   "type": "module",
   "main": "./dist/index.js",
@@ -103,6 +103,7 @@
     "clsx": "^2.1.0",
     "color": "^5.0.2",
     "date-fns": "^4.1.0",
+    "embla-carousel-autoplay": "^8.6.0",
     "embla-carousel-react": "^8.6.0",
     "framer-motion": "^12.29.0",
     "input-otp": "^1.4.2",