@minidev.fun/ui 1.0.1

package/llm/contributing.llm.md

@@ -0,0 +1,282 @@
+# Contributing to @minidev.fun/ui (LLM Guide)
+
+Technical reference for AI assistants modifying this package.
+
+## Critical Rules
+
+1. **Never export defaults** - Named exports only
+2. **Always add `data-slot`** - Root element of every component
+3. **Use `type` not `interface`** - For prop definitions
+4. **`"use client"` only when needed** - Only for components using React hooks
+5. **Run type-check** - `yarn type-check` must pass before committing
+
+## File Locations
+
+```
+src/
+├── components/
+│   ├── ui/                    # Base UI components
+│   │   ├── button.tsx
+│   │   └── stories/           # Storybook stories
+│   │       └── button.stories.tsx
+│   └── minidev/                # Minidev-specific components
+│       ├── typography/
+│       ├── color-mode/
+│       └── first-light/
+├── hooks/                     # Custom hooks
+├── lib/                       # Utilities (cn, variants)
+└── styles/                    # CSS and themes
+    └── themes/
+
+llm/                          # LLM documentation
+├── components/                # Per-component docs
+├── index.llm.md              # Package overview
+├── hooks.llm.md
+├── utilities.llm.md
+└── theming.llm.md
+
+package.json                   # Exports map (auto-generated)
+```
+
+## Component Template
+
+````tsx
+// Add "use client" ONLY if component uses hooks
+import { Primitive } from "@base-ui/react/primitive";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const componentVariants = cva("base-classes", {
+  variants: {
+    variant: {
+      default: "...",
+      secondary: "...",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+  },
+});
+
+type ComponentProps = Primitive.Props & VariantProps<typeof componentVariants>;
+
+/**
+ * Brief description.
+ *
+ * @example
+ * ```tsx
+ * <Component>Content</Component>
+ * ```
+ */
+function Component({ className, variant, ...props }: ComponentProps) {
+  return (
+    <Primitive
+      data-slot="component"
+      className={cn(componentVariants({ variant, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Component, componentVariants, type ComponentProps };
+````
+
+## Story Template
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { Component } from "../component";
+
+const meta: Meta<typeof Component> = {
+  title: "UI/Component",
+  component: Component,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Component>;
+
+export const Default: Story = {
+  args: { children: "Example" },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Component variant="default">Default</Component>
+      <Component variant="secondary">Secondary</Component>
+    </div>
+  ),
+};
+```
+
+## LLM Documentation Template
+
+```markdown
+# ComponentName
+
+One sentence description.
+
+## Import
+
+\`\`\`tsx
+import { Component } from "@minidev.fun/ui/component"
+\`\`\`
+
+## Usage
+
+\`\`\`tsx
+<Component>Content</Component>
+\`\`\`
+
+## Props
+
+| Prop    | Type                     | Default   | Description  |
+| ------- | ------------------------ | --------- | ------------ |
+| variant | "default" \| "secondary" | "default" | Visual style |
+
+## Examples
+
+### With variant
+
+\`\`\`tsx
+<Component variant="secondary">Secondary</Component>
+\`\`\`
+```
+
+## data-slot Convention
+
+Every component root element MUST have `data-slot`:
+
+```tsx
+// Single component
+<Button data-slot="button" />
+
+// Compound component
+<Dialog data-slot="dialog">
+  <DialogTrigger data-slot="dialog-trigger" />
+  <DialogContent data-slot="dialog-content">
+    <DialogHeader data-slot="dialog-header" />
+    <DialogTitle data-slot="dialog-title" />
+    <DialogDescription data-slot="dialog-description" />
+    <DialogFooter data-slot="dialog-footer" />
+  </DialogContent>
+</Dialog>
+```
+
+## "use client" Rules
+
+**ADD** when component:
+
+- Uses `useState`, `useEffect`, `useRef`, `useContext`
+- Uses custom hooks (`useColorMode`, `useMobile`)
+- Has event handlers that need client hydration
+
+**OMIT** when component:
+
+- Is a pure wrapper around Base UI primitive
+- Only passes props through
+- Has no React hooks
+
+Current components with `"use client"`:
+
+- avatar, calendar, carousel, chart, collapsible
+- combobox, command, dialog, drawer, field
+- hover-card, input-otp, label, progress, resizable
+- select, sidebar, slider, switch, tabs
+- toggle-group, tooltip
+- color-mode/_, first-light/_
+
+## Semantic Color Tokens
+
+```css
+/* Backgrounds */
+bg-background, bg-card, bg-popover, bg-muted, bg-accent
+
+/* Foregrounds */
+text-foreground, text-muted-foreground, text-card-foreground
+
+/* Status */
+bg-primary, text-primary-foreground
+bg-secondary, text-secondary-foreground
+bg-destructive, text-destructive
+bg-success, text-success
+bg-warning, text-warning
+bg-info, text-info
+
+/* Borders */
+border-border, border-input, border-ring
+```
+
+## Package.json Exports
+
+Exports are auto-generated by `scripts/generate-exports.ts` during build.
+
+Each component gets an entry:
+
+```json
+{
+  "./button": {
+    "types": "./dist/components/ui/button.d.ts",
+    "import": "./dist/components/ui/button.js"
+  }
+}
+```
+
+## Validation Commands
+
+```bash
+# Must pass before commit
+yarn type-check    # TypeScript
+yarn lint          # ESLint
+yarn build         # Build check
+
+# Development
+yarn storybook     # Visual testing
+```
+
+## Common Patterns
+
+### Polymorphism with `render` prop
+
+```tsx
+<Button render={<a href="/link" />}>Link Button</Button>
+```
+
+### Compound Components
+
+```tsx
+<Dialog>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>
+    <DialogTitle>Title</DialogTitle>
+    <DialogDescription>Description</DialogDescription>
+  </DialogContent>
+</Dialog>
+```
+
+### Forwarding refs (handled by Base UI)
+
+```tsx
+// Base UI handles ref forwarding automatically
+// No need for forwardRef wrapper
+function Component(props: ComponentProps) {
+  return <Primitive {...props} />;
+}
+```
+
+### Icon sizing
+
+```tsx
+// Icons auto-size via [&_svg:not([class*='size-'])]:size-4
+<Button>
+  <PlusIcon /> {/* Inherits size-4 */}
+  Add Item
+</Button>
+```
+
+## Debugging Tips
+
+- Check `data-slot` attributes in DevTools for component boundaries
+- Use `?path=/story/ui-button--default` in Storybook URL
+- Run `yarn type-check 2>&1 | head -20` for focused error output

package/llm/hooks.llm.md

@@ -0,0 +1,91 @@
+# Hooks
+
+React hooks provided by @minidev.fun/ui.
+
+## useIsMobile
+
+Detects mobile viewport using `matchMedia`. Returns reactive boolean.
+
+### Import
+
+```tsx
+import { useIsMobile } from "@minidev.fun/ui/use-mobile";
+```
+
+### Returns
+
+| Type      | Description                                     |
+| --------- | ----------------------------------------------- |
+| `boolean` | `true` when viewport < 768px, `false` otherwise |
+
+### Behavior
+
+- Returns `false` during SSR (hydration-safe)
+- Updates reactively on viewport resize
+- Uses `matchMedia` for performance (no resize listener spam)
+- Breakpoint: 768px (CSS `md:` equivalent)
+
+### Example: Responsive Navigation
+
+```tsx
+import { useIsMobile } from "@minidev.fun/ui/use-mobile";
+
+function ResponsiveNav() {
+  const isMobile = useIsMobile();
+  return isMobile ? <MobileNav /> : <DesktopNav />;
+}
+```
+
+### Example: Responsive Modal
+
+Use Sheet for mobile, Dialog for desktop:
+
+```tsx
+import { useIsMobile } from "@minidev.fun/ui/use-mobile";
+import { Sheet, SheetContent } from "@minidev.fun/ui/sheet";
+import { Dialog, DialogContent } from "@minidev.fun/ui/dialog";
+
+function ResponsiveModal({ open, onOpenChange, children }) {
+  const isMobile = useIsMobile();
+
+  if (isMobile) {
+    return (
+      <Sheet open={open} onOpenChange={onOpenChange}>
+        <SheetContent side="bottom">{children}</SheetContent>
+      </Sheet>
+    );
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>{children}</DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### Example: Conditional Rendering
+
+```tsx
+import { useIsMobile } from "@minidev.fun/ui/use-mobile";
+
+function Dashboard() {
+  const isMobile = useIsMobile();
+
+  return (
+    <div className="flex">
+      {!isMobile && <Sidebar />}
+      <main className="flex-1">
+        <Content />
+      </main>
+      {isMobile && <MobileBottomNav />}
+    </div>
+  );
+}
+```
+
+### Related
+
+- [Sheet](./components/sheet.llm.md) - Often used with mobile detection for bottom sheets
+- [Drawer](./components/drawer.llm.md) - Mobile-first bottom sheet component
+- [Sidebar](./components/sidebar.llm.md) - Responsive sidebar that can use mobile detection

package/llm/index.llm.md

@@ -0,0 +1,188 @@
+# @minidev.fun/ui
+
+> React component library built on Base UI primitives + Tailwind CSS v4. 53 production-ready components with per-component imports, SSR-safe dark mode, and two visual themes.
+
+## For AI Agents
+
+**How to use this documentation:**
+
+1. **Start here** for quick reference and component discovery
+2. **Load specific component docs** from `./components/{name}.llm.md` when working with that component
+3. **Load theming.llm.md** when dealing with themes, colors, or dark mode
+4. **Each doc is self-contained** with imports, props, examples, and accessibility info
+
+**Key patterns to remember:**
+
+- Import path: `import { X } from "@minidev.fun/ui/x"` (lowercase, kebab-case)
+- All components have `data-slot` attributes for CSS targeting
+- Compound components export multiple parts from same path
+- `render` prop (not `asChild`) for polymorphism
+
+## Quick Start
+
+```tsx
+import { Button } from "@minidev.fun/ui/button";
+import { Card, CardHeader, CardContent } from "@minidev.fun/ui/card";
+import "@minidev.fun/ui/themes/minidev-sunset";
+
+export function App() {
+  return (
+    <Card>
+      <CardHeader>Welcome</CardHeader>
+      <CardContent>
+        <Button>Get Started</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Import Pattern
+
+Each component has its own entry point:
+
+```tsx
+import { Button } from "@minidev.fun/ui/button";
+import { Dialog, DialogTrigger, DialogContent } from "@minidev.fun/ui/dialog";
+import { Input } from "@minidev.fun/ui/input";
+import { cn } from "@minidev.fun/ui/utils";
+```
+
+## Themes
+
+```tsx
+// Minidev Sunset - elegant surfaces (default)
+import "@minidev.fun/ui/themes/minidev-sunset";
+
+// First Light - hand-drawn wireframe aesthetic
+import "@minidev.fun/ui/themes/first-light";
+```
+
+## Color Mode
+
+SSR-safe dark mode with automatic system detection:
+
+```tsx
+import { ColorModeInitializer, ColorModeToggle } from "@minidev.fun/ui/color-mode";
+
+// In layout.tsx <head>
+<ColorModeInitializer />
+
+// Anywhere for user control
+<ColorModeToggle />
+```
+
+## Component Index
+
+### Core Inputs
+
+| Component   | Import Path                    | Description         |
+| ----------- | ------------------------------ | ------------------- |
+| Button      | `@minidev.fun/ui/button`       | 9 variants, 8 sizes |
+| Checkbox    | `@minidev.fun/ui/checkbox`     | Boolean toggle      |
+| Input       | `@minidev.fun/ui/input`        | Text input          |
+| RadioGroup  | `@minidev.fun/ui/radio-group`  | Single selection    |
+| Select      | `@minidev.fun/ui/select`       | Dropdown selection  |
+| Slider      | `@minidev.fun/ui/slider`       | Range input         |
+| Switch      | `@minidev.fun/ui/switch`       | Toggle switch       |
+| Textarea    | `@minidev.fun/ui/textarea`     | Multi-line text     |
+| Toggle      | `@minidev.fun/ui/toggle`       | Pressable toggle    |
+| ToggleGroup | `@minidev.fun/ui/toggle-group` | Multiple toggles    |
+| Combobox    | `@minidev.fun/ui/combobox`     | Searchable select   |
+
+### Form & Field
+
+| Component   | Import Path                    | Description        |
+| ----------- | ------------------------------ | ------------------ |
+| ButtonGroup | `@minidev.fun/ui/button-group` | Connected buttons  |
+| Calendar    | `@minidev.fun/ui/calendar`     | Date picker        |
+| Field       | `@minidev.fun/ui/field`        | Form field wrapper |
+| InputGroup  | `@minidev.fun/ui/input-group`  | Input with addons  |
+| InputOTP    | `@minidev.fun/ui/input-otp`    | One-time password  |
+| Label       | `@minidev.fun/ui/label`        | Form labels        |
+
+### Layout & Structure
+
+| Component   | Import Path                    | Description         |
+| ----------- | ------------------------------ | ------------------- |
+| Accordion   | `@minidev.fun/ui/accordion`    | Expandable sections |
+| AspectRatio | `@minidev.fun/ui/aspect-ratio` | Maintain ratio      |
+| Card        | `@minidev.fun/ui/card`         | Content container   |
+| Collapsible | `@minidev.fun/ui/collapsible`  | Show/hide content   |
+| Resizable   | `@minidev.fun/ui/resizable`    | Resizable panels    |
+| ScrollArea  | `@minidev.fun/ui/scroll-area`  | Custom scrollbars   |
+| Separator   | `@minidev.fun/ui/separator`    | Visual divider      |
+| Table       | `@minidev.fun/ui/table`        | Data tables         |
+
+### Navigation & Menus
+
+| Component      | Import Path                       | Description      |
+| -------------- | --------------------------------- | ---------------- |
+| Breadcrumb     | `@minidev.fun/ui/breadcrumb`      | Path indicator   |
+| ContextMenu    | `@minidev.fun/ui/context-menu`    | Right-click menu |
+| DropdownMenu   | `@minidev.fun/ui/dropdown-menu`   | Trigger dropdown |
+| Menubar        | `@minidev.fun/ui/menubar`         | Horizontal menu  |
+| NavigationMenu | `@minidev.fun/ui/navigation-menu` | Site navigation  |
+| Pagination     | `@minidev.fun/ui/pagination`      | Page navigation  |
+| Sidebar        | `@minidev.fun/ui/sidebar`         | Collapsible nav  |
+| Tabs           | `@minidev.fun/ui/tabs`            | Tabbed content   |
+
+### Overlays & Dialogs
+
+| Component   | Import Path                    | Description        |
+| ----------- | ------------------------------ | ------------------ |
+| AlertDialog | `@minidev.fun/ui/alert-dialog` | Confirmation       |
+| Dialog      | `@minidev.fun/ui/dialog`       | Modal dialog       |
+| Drawer      | `@minidev.fun/ui/drawer`       | Bottom drawer      |
+| HoverCard   | `@minidev.fun/ui/hover-card`   | Rich hover preview |
+| Popover     | `@minidev.fun/ui/popover`      | Floating content   |
+| Sheet       | `@minidev.fun/ui/sheet`        | Side panel         |
+| Tooltip     | `@minidev.fun/ui/tooltip`      | Hover info         |
+
+### Feedback & Status
+
+| Component | Import Path                | Description          |
+| --------- | -------------------------- | -------------------- |
+| Alert     | `@minidev.fun/ui/alert`    | Contextual messages  |
+| Badge     | `@minidev.fun/ui/badge`    | Status indicators    |
+| Empty     | `@minidev.fun/ui/empty`    | Empty state          |
+| Progress  | `@minidev.fun/ui/progress` | Progress bars        |
+| Skeleton  | `@minidev.fun/ui/skeleton` | Loading placeholders |
+| Sonner    | `@minidev.fun/ui/sonner`   | Toast notifications  |
+| Spinner   | `@minidev.fun/ui/spinner`  | Loading spinner      |
+
+### Advanced
+
+| Component | Import Path                | Description        |
+| --------- | -------------------------- | ------------------ |
+| Avatar    | `@minidev.fun/ui/avatar`   | User avatars       |
+| Carousel  | `@minidev.fun/ui/carousel` | Content slider     |
+| Chart     | `@minidev.fun/ui/chart`    | Recharts wrapper   |
+| Command   | `@minidev.fun/ui/command`  | Command palette    |
+| Kbd       | `@minidev.fun/ui/kbd`      | Keyboard shortcuts |
+| Item      | `@minidev.fun/ui/item`     | List items         |
+
+### Typography
+
+| Component  | Import Path                  | Description      |
+| ---------- | ---------------------------- | ---------------- |
+| Title      | `@minidev.fun/ui/typography` | Headings (h1-h6) |
+| Text       | `@minidev.fun/ui/typography` | Paragraph text   |
+| Code       | `@minidev.fun/ui/typography` | Inline code      |
+| Blockquote | `@minidev.fun/ui/typography` | Quote blocks     |
+
+### Theme Utilities
+
+| Component            | Import Path                   | Description               |
+| -------------------- | ----------------------------- | ------------------------- |
+| ColorModeInitializer | `@minidev.fun/ui/color-mode`  | FOUC prevention script    |
+| ColorModeToggle      | `@minidev.fun/ui/color-mode`  | Mode switcher dropdown    |
+| useColorMode         | `@minidev.fun/ui/color-mode`  | Programmatic control hook |
+| FirstLightFilters    | `@minidev.fun/ui/first-light` | SVG wobble filters        |
+
+## Additional Documentation
+
+- [Theming](./theming.llm.md) - Themes, color mode, CSS variables, customization
+- [Hooks](./hooks.llm.md) - useIsMobile responsive hook
+- [Utilities](./utilities.llm.md) - cn() class merging utility
+- [Contributing](./contributing.llm.md) - Component patterns, data-slot, templates