@minidev.fun/ui 1.0.1

package/llm/components/scroll-area.llm.md

@@ -0,0 +1,322 @@
+# ScrollArea Component
+
+## Overview
+
+The ScrollArea component provides a customizable scrollable container with styled scrollbars, built on Base UI's ScrollArea primitive. It offers automatic overflow detection, custom scrollbar styling, and support for both vertical and horizontal scrolling.
+
+## Component Exports
+
+### ScrollArea
+
+Main scrollable container component with custom-styled scrollbars.
+
+**Props**: `ScrollAreaProps` (extends `ScrollAreaPrimitive.Root.Props`)
+
+- `className?: string` - Additional CSS classes to apply
+- `children: React.ReactNode` - Content to be rendered within the scrollable area
+- All Base UI ScrollArea.Root props
+
+**Key Features**:
+
+- Automatic overflow detection
+- Custom-styled scrollbars with border-based color
+- Focus ring on keyboard navigation
+- Inherits border radius from parent styling
+- Smooth transitions for focus states
+
+### ScrollBar
+
+Custom scrollbar component that can be used independently or within ScrollArea.
+
+**Props**: `ScrollBarProps` (extends `ScrollAreaPrimitive.Scrollbar.Props`)
+
+- `className?: string` - Additional CSS classes to apply
+- `orientation?: "vertical" | "horizontal"` - Scrollbar orientation (default: "vertical")
+- All Base UI ScrollArea.Scrollbar props
+
+**Key Features**:
+
+- Draggable thumb for scroll control
+- Adaptive sizing based on orientation (2.5 units height/width)
+- Touch-optimized for mobile devices
+- Rounded scrollbar thumb
+
+## Usage Examples
+
+### Basic Vertical Scrolling
+
+```tsx
+import { ScrollArea } from "@minidev.fun/ui/scroll-area";
+
+function ContentList() {
+  return (
+    <ScrollArea className="h-72 w-48 rounded-md border p-4">
+      <div className="space-y-4">
+        {items.map((item) => (
+          <div key={item.id}>{item.content}</div>
+        ))}
+      </div>
+    </ScrollArea>
+  );
+}
+```
+
+### Horizontal Scrolling
+
+```tsx
+import { ScrollArea } from "@minidev.fun/ui/scroll-area";
+
+function HorizontalGallery() {
+  return (
+    <ScrollArea className="w-96 whitespace-nowrap rounded-md border">
+      <div className="flex gap-4 p-4">
+        {images.map((img) => (
+          <img
+            key={img.id}
+            src={img.url}
+            alt={img.alt}
+            className="h-40 w-auto"
+          />
+        ))}
+      </div>
+    </ScrollArea>
+  );
+}
+```
+
+### Chat-Style Scrolling
+
+```tsx
+import { ScrollArea } from "@minidev.fun/ui/scroll-area";
+
+function ChatMessages() {
+  return (
+    <ScrollArea className="h-[600px] rounded-lg border p-4">
+      <div className="flex flex-col gap-2">
+        {messages.map((message) => (
+          <div key={message.id} className="rounded-lg bg-muted p-3">
+            <p className="text-sm font-medium">{message.author}</p>
+            <p className="text-sm">{message.content}</p>
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  );
+}
+```
+
+### Sidebar Navigation
+
+```tsx
+import { ScrollArea } from "@minidev.fun/ui/scroll-area";
+
+function Sidebar() {
+  return (
+    <aside className="w-64 border-r">
+      <ScrollArea className="h-screen p-4">
+        <nav className="space-y-2">
+          {navItems.map((item) => (
+            <a
+              key={item.href}
+              href={item.href}
+              className="block rounded-md px-3 py-2 hover:bg-accent"
+            >
+              {item.label}
+            </a>
+          ))}
+        </nav>
+      </ScrollArea>
+    </aside>
+  );
+}
+```
+
+### Custom Scrollbar Configuration
+
+```tsx
+import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area";
+import { ScrollBar } from "@minidev.fun/ui/scroll-area";
+
+function CustomScrollArea({ children }: { children: React.ReactNode }) {
+  return (
+    <ScrollAreaPrimitive.Root className="relative h-96 rounded-md border">
+      <ScrollAreaPrimitive.Viewport className="size-full p-4">
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar orientation="horizontal" className="bg-muted/50" />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  );
+}
+```
+
+## Component Structure
+
+```
+ScrollArea (Root container)
+├── Viewport (content wrapper with focus ring)
+│   └── {children}
+├── ScrollBar (vertical by default)
+│   └── Thumb (draggable scrollbar handle)
+└── Corner (intersection of scrollbars)
+```
+
+## Styling and Theming
+
+### Default Styles
+
+- **Root**: `relative` positioning for scrollbar placement
+- **Viewport**: Full size with inherited border radius, focus ring on keyboard navigation
+- **ScrollBar**: 2.5 units width/height depending on orientation, touch-optimized
+- **Thumb**: Rounded, uses `border` color from theme
+
+### Customization Points
+
+- Apply height/width constraints via `className` on ScrollArea
+- Customize scrollbar appearance via `className` on ScrollBar
+- Border radius is inherited from parent container
+- Colors follow the theme's `border` color token
+
+### Data Attributes
+
+- `data-slot="scroll-area"` - Root container
+- `data-slot="scroll-area-viewport"` - Content viewport
+- `data-slot="scroll-area-scrollbar"` - Scrollbar container
+- `data-slot="scroll-area-thumb"` - Scrollbar thumb
+- `data-orientation="vertical|horizontal"` - Scrollbar orientation state
+
+## Accessibility
+
+### Keyboard Navigation
+
+- **Arrow Keys**: Scroll viewport when focused
+- **Page Up/Down**: Scroll by page
+- **Home/End**: Scroll to start/end
+- **Tab**: Focus scrollbar (visible focus ring)
+
+### Screen Reader Support
+
+- Scrollable regions are properly announced
+- Scrollbar controls are keyboard accessible
+- Focus management follows standard patterns
+
+### Touch Gestures
+
+- Scrollbar is touch-optimized with `touch-none` for precise dragging
+- Natural swipe scrolling on viewport
+
+## Common Patterns
+
+### Fixed Height Content
+
+```tsx
+<ScrollArea className="h-96 rounded-md border">
+  {/* Content that exceeds 384px height will scroll */}
+</ScrollArea>
+```
+
+### Full Viewport Height
+
+```tsx
+<ScrollArea className="h-screen">
+  {/* Scrolls within viewport height */}
+</ScrollArea>
+```
+
+### Responsive Heights
+
+```tsx
+<ScrollArea className="h-[50vh] md:h-[70vh] rounded-md border">
+  {/* Adapts to viewport size */}
+</ScrollArea>
+```
+
+### Preventing Text Selection During Scroll
+
+The scrollbar uses `select-none` to prevent text selection while dragging, but content remains selectable.
+
+## Base UI Integration
+
+This component wraps Base UI's ScrollArea primitive:
+
+- **Root**: Container with scroll detection
+- **Viewport**: Scrollable content area
+- **Scrollbar**: Custom scrollbar UI
+- **Thumb**: Draggable scroll indicator
+- **Corner**: Intersection element for dual scrollbars
+
+Base UI handles:
+
+- Overflow detection and scrollbar visibility
+- Scroll position synchronization
+- Touch and mouse interactions
+- Accessibility features
+
+## Implementation Notes
+
+### Why Not Native Scrollbars?
+
+- Consistent cross-browser appearance
+- Better theming and customization
+- Touch-optimized interactions
+- Accessible keyboard controls
+
+### Performance Considerations
+
+- Viewport uses hardware-accelerated transitions
+- Scrollbar only renders when content overflows
+- Efficient re-renders with Base UI primitives
+
+### Browser Compatibility
+
+- Modern browsers with CSS Grid and Flexbox support
+- Touch events for mobile devices
+- Fallback to native scrolling if JavaScript disabled
+
+## Comparison with Similar Components
+
+### ScrollArea vs. Native Overflow
+
+- **ScrollArea**: Custom styled scrollbars, consistent appearance
+- **Native**: Browser-dependent styling, system scrollbars
+
+### When to Use ScrollArea
+
+- Consistent design across browsers and platforms
+- Custom scrollbar styling requirements
+- Need for touch-optimized scrolling
+- Keyboard navigation requirements
+
+### When to Use Native Scrolling
+
+- Simple content with minimal styling needs
+- Performance-critical rendering (native is slightly faster)
+- Desire for OS-native scrollbar appearance
+
+## Migration from Radix UI
+
+If migrating from Radix UI ScrollArea:
+
+```tsx
+// Before (Radix UI)
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
+
+<ScrollAreaPrimitive.Root>
+  <ScrollAreaPrimitive.Viewport>{children}</ScrollAreaPrimitive.Viewport>
+  <ScrollAreaPrimitive.Scrollbar orientation="vertical">
+    <ScrollAreaPrimitive.Thumb />
+  </ScrollAreaPrimitive.Scrollbar>
+</ScrollAreaPrimitive.Root>;
+
+// After (Base UI)
+import { ScrollArea } from "@minidev.fun/ui/scroll-area";
+
+<ScrollArea className="h-96">{children}</ScrollArea>;
+```
+
+Key differences:
+
+- Base UI uses simpler composition
+- Automatic scrollbar rendering
+- Focus ring styling built-in
+- Data attributes follow `data-slot` pattern

package/llm/components/select.llm.md

@@ -0,0 +1,338 @@
+# Select
+
+Dropdown component for selecting a single value from a list of options with grouping, icons, and keyboard navigation.
+
+## Import
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "@minidev.fun/ui/select";
+```
+
+## Anatomy
+
+```tsx
+<Select>
+  <SelectTrigger>
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Group Label</SelectLabel>
+      <SelectItem value="1">Option 1</SelectItem>
+      <SelectItem value="2">Option 2</SelectItem>
+    </SelectGroup>
+    <SelectSeparator />
+    <SelectGroup>
+      <SelectLabel>Another Group</SelectLabel>
+      <SelectItem value="3">Option 3</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+## Components
+
+| Component              | Description                                                           |
+| ---------------------- | --------------------------------------------------------------------- |
+| Select                 | Root container, manages selection state and keyboard navigation       |
+| SelectTrigger          | Button that opens the dropdown, includes chevron icon automatically   |
+| SelectValue            | Displays the selected item's value or placeholder                     |
+| SelectContent          | Dropdown popup with automatic portal, positioning, and scroll buttons |
+| SelectGroup            | Groups related items under a label                                    |
+| SelectLabel            | Non-selectable label for a group                                      |
+| SelectItem             | Individual selectable option with automatic check indicator           |
+| SelectSeparator        | Visual divider between groups                                         |
+| SelectScrollUpButton   | Scroll indicator at top (automatic)                                   |
+| SelectScrollDownButton | Scroll indicator at bottom (automatic)                                |
+
+## Props
+
+### Select
+
+| Prop          | Type                            | Default | Description                        |
+| ------------- | ------------------------------- | ------- | ---------------------------------- |
+| value         | string                          | -       | Controlled selected value          |
+| defaultValue  | string                          | -       | Uncontrolled default value         |
+| onValueChange | (value: string \| null) => void | -       | Called when selection changes      |
+| disabled      | boolean                         | false   | Disables the entire select         |
+| name          | string                          | -       | Name attribute for form submission |
+
+### SelectTrigger
+
+Button that opens the dropdown. Automatically includes chevron icon.
+
+| Prop      | Type              | Default   | Description            |
+| --------- | ----------------- | --------- | ---------------------- |
+| size      | "sm" \| "default" | "default" | Trigger button size    |
+| className | string            | -         | Additional CSS classes |
+
+### SelectValue
+
+Displays the selected value or placeholder. Automatically shows selected item text.
+
+| Prop        | Type   | Default | Description                       |
+| ----------- | ------ | ------- | --------------------------------- |
+| placeholder | string | -       | Text shown when no value selected |
+| className   | string | -       | Additional CSS classes            |
+
+### SelectContent
+
+Automatically renders in a portal with backdrop overlay, positioning, and scroll indicators.
+
+| Prop                 | Type                                   | Default  | Description                                    |
+| -------------------- | -------------------------------------- | -------- | ---------------------------------------------- |
+| side                 | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side to position relative to trigger |
+| sideOffset           | number                                 | 4        | Distance from trigger in pixels                |
+| align                | "start" \| "center" \| "end"           | "center" | Alignment relative to trigger                  |
+| alignOffset          | number                                 | 0        | Offset from aligned position                   |
+| alignItemWithTrigger | boolean                                | true     | Whether to align selected item with trigger    |
+| className            | string                                 | -        | Additional CSS classes                         |
+
+### SelectItem
+
+Individual option. Automatically shows check icon when selected.
+
+| Prop      | Type    | Default | Description                                                   |
+| --------- | ------- | ------- | ------------------------------------------------------------- |
+| value     | string  | -       | **Required.** Unique value for this option                    |
+| disabled  | boolean | false   | Disables this specific item                                   |
+| label     | string  | -       | Label for keyboard text navigation (defaults to text content) |
+| className | string  | -       | Additional CSS classes                                        |
+
+### SelectGroup
+
+| Prop      | Type   | Default | Description            |
+| --------- | ------ | ------- | ---------------------- |
+| className | string | -       | Additional CSS classes |
+
+### SelectLabel
+
+| Prop      | Type   | Default | Description            |
+| --------- | ------ | ------- | ---------------------- |
+| className | string | -       | Additional CSS classes |
+
+### SelectSeparator
+
+| Prop      | Type   | Default | Description            |
+| --------- | ------ | ------- | ---------------------- |
+| className | string | -       | Additional CSS classes |
+
+## Data Attributes (for styling)
+
+### SelectTrigger
+
+| Attribute        | When Present                                |
+| ---------------- | ------------------------------------------- |
+| data-size        | Always present with value "sm" or "default" |
+| data-placeholder | No value selected                           |
+| aria-invalid     | Invalid state (for forms)                   |
+
+### SelectItem
+
+| Attribute        | When Present                 |
+| ---------------- | ---------------------------- |
+| data-selected    | Item is currently selected   |
+| data-highlighted | Item is keyboard-highlighted |
+| data-disabled    | Item is disabled             |
+
+### SelectContent
+
+| Attribute   | When Present                          |
+| ----------- | ------------------------------------- |
+| data-open   | Popup is open                         |
+| data-closed | Popup is closed                       |
+| data-side   | Position side (top/right/bottom/left) |
+
+## Examples
+
+### Basic Select
+
+```tsx
+<Select defaultValue="option2">
+  <SelectTrigger className="w-[200px]">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">Option 1</SelectItem>
+    <SelectItem value="option2">Option 2</SelectItem>
+    <SelectItem value="option3">Option 3</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Controlled with State
+
+```tsx
+const [region, setRegion] = useState("us-east-1")
+
+<Select value={region} onValueChange={(v) => v && setRegion(v)}>
+  <SelectTrigger className="w-full">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="us-east-1">US East (N. Virginia)</SelectItem>
+    <SelectItem value="us-west-2">US West (Oregon)</SelectItem>
+    <SelectItem value="eu-west-1">EU (Ireland)</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### With Icons
+
+```tsx
+<Select defaultValue="admin">
+  <SelectTrigger className="w-[280px]">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="admin">
+      <SettingsIcon data-icon="inline-start" />
+      Administrator
+    </SelectItem>
+    <SelectItem value="user">
+      <UserIcon data-icon="inline-start" />
+      Regular User
+    </SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Grouped Options
+
+```tsx
+<Select defaultValue="react">
+  <SelectTrigger className="w-[280px]">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Frontend</SelectLabel>
+      <SelectItem value="react">React</SelectItem>
+      <SelectItem value="vue">Vue</SelectItem>
+    </SelectGroup>
+    <SelectSeparator />
+    <SelectGroup>
+      <SelectLabel>Backend</SelectLabel>
+      <SelectItem value="node">Node.js</SelectItem>
+      <SelectItem value="python">Python</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+### Form Integration
+
+```tsx
+<div className="space-y-2">
+  <label htmlFor="country" className="text-sm font-medium">
+    Country
+  </label>
+  <Select defaultValue="us">
+    <SelectTrigger id="country">
+      <SelectValue />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="us">United States</SelectItem>
+      <SelectItem value="uk">United Kingdom</SelectItem>
+      <SelectItem value="ca">Canada</SelectItem>
+    </SelectContent>
+  </Select>
+  <p className="text-muted-foreground text-xs">
+    Select your country of residence.
+  </p>
+</div>
+```
+
+### Small Size
+
+```tsx
+<Select defaultValue="sm">
+  <SelectTrigger size="sm" className="w-[180px]">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="sm">Small option</SelectItem>
+    <SelectItem value="sm2">Another small</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Disabled States
+
+```tsx
+// Disabled select
+<Select defaultValue="option1" disabled>
+  <SelectTrigger className="w-[200px]">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">Option 1</SelectItem>
+  </SelectContent>
+</Select>
+
+// Disabled items
+<Select defaultValue="available">
+  <SelectTrigger className="w-[200px]">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="available">Available</SelectItem>
+    <SelectItem value="unavailable" disabled>
+      Unavailable
+    </SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Placeholder
+
+```tsx
+<Select>
+  <SelectTrigger className="w-[280px]">
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Keyboard
+
+| Key             | Action                                   |
+| --------------- | ---------------------------------------- |
+| Space / Enter   | Open dropdown (when closed)              |
+| Space / Enter   | Select highlighted item (when open)      |
+| Escape          | Close dropdown                           |
+| ArrowDown       | Highlight next item                      |
+| ArrowUp         | Highlight previous item                  |
+| Home            | Highlight first item                     |
+| End             | Highlight last item                      |
+| Type characters | Jump to item starting with typed text    |
+| Tab             | Close and move to next focusable element |
+
+## Accessibility
+
+- Uses `role="combobox"` on trigger with proper ARIA attributes
+- Implements `aria-expanded`, `aria-controls`, and `aria-activedescendant`
+- Selected items marked with `aria-selected="true"`
+- Disabled items use `aria-disabled="true"`
+- Keyboard navigation follows ARIA combobox pattern
+- Focus management returns to trigger on close
+- Screen readers announce selection changes
+
+## Related
+
+- [Combobox](/components/combobox) - Searchable select with filtering
+- [Radio Group](/components/radio-group) - Single selection from visible options
+- [Command](/components/command) - Command palette with search