@minidev.fun/ui 1.0.1

package/llm/components/popover.llm.md

@@ -0,0 +1,274 @@
+# Popover
+
+Floating content panel anchored to a trigger element for contextual information, forms, or interactive content.
+
+## Import
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverDescription,
+} from "@minidev.fun/ui/popover";
+```
+
+## Anatomy
+
+```tsx
+<Popover>
+  <PopoverTrigger>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <PopoverHeader>
+      <PopoverTitle>Title</PopoverTitle>
+      <PopoverDescription>Description</PopoverDescription>
+    </PopoverHeader>
+    {/* Content */}
+  </PopoverContent>
+</Popover>
+```
+
+## Components
+
+| Component          | Description                                    |
+| ------------------ | ---------------------------------------------- |
+| Popover            | Root container managing open state             |
+| PopoverTrigger     | Button that opens the popover                  |
+| PopoverContent     | Main content panel with portal and positioning |
+| PopoverHeader      | Optional wrapper for title and description     |
+| PopoverTitle       | Heading label (h2 element)                     |
+| PopoverDescription | Optional description text                      |
+
+## Props
+
+### Popover
+
+Root component managing state. Use `open`/`onOpenChange` for controlled state.
+
+| Prop         | Type                    | Default | Description                                                                          |
+| ------------ | ----------------------- | ------- | ------------------------------------------------------------------------------------ |
+| open         | boolean                 | -       | Controlled open state                                                                |
+| defaultOpen  | boolean                 | false   | Initial open state (uncontrolled)                                                    |
+| onOpenChange | (open: boolean) => void | -       | Callback when open state changes                                                     |
+| modal        | boolean \| "trap-focus" | false   | Modal behavior: `true` locks scroll and traps focus, `"trap-focus"` only traps focus |
+
+### PopoverTrigger
+
+Opens the popover when clicked. Renders a button by default.
+
+| Prop        | Type         | Default | Description                              |
+| ----------- | ------------ | ------- | ---------------------------------------- |
+| render      | ReactElement | -       | Custom element to use as trigger         |
+| openOnHover | boolean      | false   | Open popover on hover instead of click   |
+| delay       | number       | 300     | Hover delay in ms (requires openOnHover) |
+
+### PopoverContent
+
+Automatically renders portal and positioner. Includes fade and zoom animations.
+
+| Prop        | Type                                   | Default  | Description                                    |
+| ----------- | -------------------------------------- | -------- | ---------------------------------------------- |
+| side        | "top" \| "right" \| "bottom" \| "left" | "bottom" | Which side of trigger to display on            |
+| align       | "start" \| "center" \| "end"           | "center" | Alignment relative to trigger                  |
+| sideOffset  | number                                 | 4        | Distance from trigger in pixels                |
+| alignOffset | number                                 | 0        | Offset along alignment axis in pixels          |
+| className   | string                                 | -        | Additional CSS classes (default width is w-72) |
+
+### PopoverHeader
+
+Optional container for title and description with consistent spacing.
+
+Standard `div` props.
+
+### PopoverTitle
+
+Heading label with ARIA attributes. Renders h2 element.
+
+Standard Base UI Title props (className, render, etc).
+
+### PopoverDescription
+
+Optional description text styled with muted foreground.
+
+Standard Base UI Description props (className, render, etc).
+
+## Data Attributes
+
+Available on PopoverContent for styling:
+
+| Attribute           | When Present                                  |
+| ------------------- | --------------------------------------------- |
+| data-open           | Popover is open                               |
+| data-closed         | Popover is closed                             |
+| data-side           | Value is current side (top/right/bottom/left) |
+| data-starting-style | During opening animation                      |
+| data-ending-style   | During closing animation                      |
+
+## Examples
+
+### User Profile Preview
+
+```tsx
+<Popover>
+  <PopoverTrigger>
+    <button className="flex items-center gap-2">
+      <Avatar />
+      <span>vitalik.eth</span>
+    </button>
+  </PopoverTrigger>
+  <PopoverContent className="w-80" side="bottom" align="start">
+    <div className="space-y-3">
+      <div className="flex items-start gap-3">
+        <Avatar size="lg" />
+        <div className="flex-1">
+          <p className="font-semibold">vitalik.eth</p>
+          <p className="text-muted-foreground text-sm">@vitalik</p>
+        </div>
+        <Button size="sm">Follow</Button>
+      </div>
+      <p className="text-sm">Creator of Ethereum...</p>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
+### Filter Form
+
+```tsx
+function FilterPopover() {
+  const [open, setOpen] = useState(false);
+  const [dateRange, setDateRange] = useState("last-7-days");
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger>
+        <Button variant="outline" size="sm">
+          <SettingsIcon className="mr-2 size-4" />
+          Filters
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-80" side="bottom" align="end">
+        <PopoverHeader>
+          <PopoverTitle>Filter Options</PopoverTitle>
+          <PopoverDescription>Customize the data displayed</PopoverDescription>
+        </PopoverHeader>
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="date-range">Date Range</Label>
+            <select
+              id="date-range"
+              value={dateRange}
+              onChange={(e) => setDateRange(e.target.value)}
+            >
+              <option value="last-7-days">Last 7 days</option>
+              <option value="last-30-days">Last 30 days</option>
+            </select>
+          </div>
+          <div className="flex justify-end gap-2">
+            <Button variant="ghost" size="sm" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button size="sm" onClick={() => setOpen(false)}>
+              Apply
+            </Button>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+### Contextual Help
+
+```tsx
+<div className="flex items-center gap-2">
+  <Label htmlFor="api-key">API Key</Label>
+  <Popover>
+    <PopoverTrigger>
+      <button className="text-muted-foreground hover:text-foreground">
+        <HelpCircleIcon className="size-4" />
+      </button>
+    </PopoverTrigger>
+    <PopoverContent className="w-80" side="right">
+      <PopoverHeader>
+        <PopoverTitle>About API Keys</PopoverTitle>
+      </PopoverHeader>
+      <div className="space-y-2 text-sm">
+        <p>API keys authenticate requests to the Minidev API...</p>
+        <ul className="text-muted-foreground ml-4 list-disc space-y-1">
+          <li>Production keys have higher rate limits</li>
+          <li>Development keys are for testing only</li>
+        </ul>
+      </div>
+    </PopoverContent>
+  </Popover>
+</div>
+```
+
+### Custom Trigger Element
+
+```tsx
+<Popover>
+  <PopoverTrigger>
+    <Button variant="ghost" size="icon-sm">
+      <InfoIcon className="size-4" />
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-80" side="left">
+    <PopoverHeader>
+      <PopoverTitle>Billing Information</PopoverTitle>
+      <PopoverDescription>Your subscription details</PopoverDescription>
+    </PopoverHeader>
+    <div className="space-y-3 text-sm">
+      <div className="flex justify-between">
+        <span className="text-muted-foreground">Current plan</span>
+        <span className="font-medium">Pro ($99/mo)</span>
+      </div>
+      <div className="flex justify-between">
+        <span className="text-muted-foreground">Next charge</span>
+        <span className="font-medium">$99.00</span>
+      </div>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
+### Hover Trigger
+
+```tsx
+<Popover>
+  <PopoverTrigger openOnHover delay={200}>
+    <span className="underline decoration-dotted">Hover me</span>
+  </PopoverTrigger>
+  <PopoverContent side="top">
+    <p className="text-sm">This opens on hover with 200ms delay</p>
+  </PopoverContent>
+</Popover>
+```
+
+## Keyboard
+
+| Key    | Action                        |
+| ------ | ----------------------------- |
+| Escape | Close popover                 |
+| Tab    | Navigate focus within popover |
+
+## Accessibility
+
+- PopoverTitle automatically provides `aria-labelledby` for the popover
+- PopoverDescription provides `aria-describedby` when present
+- Focus is trapped within popover when `modal` is true or "trap-focus"
+- Popover closes on Escape key press
+- Focus returns to trigger when popover closes
+
+## Related
+
+- **Tooltip** - For simple text hints without interaction
+- **Dropdown Menu** - For menus with selectable actions
+- **Dialog** - For modal content requiring user action
+- **Hover Card** - Similar to Popover but specifically for hover interactions

package/llm/components/progress.llm.md

@@ -0,0 +1,260 @@
+# Progress
+
+Progress bar for displaying task completion, loading states, and quota usage.
+
+## Import
+
+```tsx
+import {
+  Progress,
+  ProgressTrack,
+  ProgressIndicator,
+  ProgressLabel,
+  ProgressValue,
+} from "@minidev.fun/ui/progress";
+```
+
+## Anatomy
+
+```tsx
+<Progress value={65}>
+  <ProgressLabel>Loading</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+## Components
+
+| Component         | Description                                               |
+| ----------------- | --------------------------------------------------------- |
+| Progress          | Root container managing progress state and rendering      |
+| ProgressLabel     | Text label describing the task                            |
+| ProgressValue     | Formatted percentage display (auto-positioned right)      |
+| ProgressTrack     | Container for the progress bar track                      |
+| ProgressIndicator | Visual bar showing completion (auto-width based on value) |
+
+## Props
+
+### Progress
+
+Root component providing progress state context to all children.
+
+| Prop             | Type                                                         | Default | Description                                     |
+| ---------------- | ------------------------------------------------------------ | ------- | ----------------------------------------------- |
+| value            | number \| null                                               | -       | Progress value 0-100, or null for indeterminate |
+| min              | number                                                       | 0       | Minimum value                                   |
+| max              | number                                                       | 100     | Maximum value                                   |
+| aria-valuetext   | string                                                       | -       | Custom accessible label for current value       |
+| getAriaValueText | (formatted: string \| null, value: number \| null) => string | -       | Function to generate accessible label           |
+| locale           | Intl.LocalesArgument                                         | -       | Locale for number formatting                    |
+| format           | Intl.NumberFormatOptions                                     | -       | Options for value formatting                    |
+| className        | string                                                       | -       | Additional CSS classes                          |
+
+### ProgressTrack
+
+Container for the progress indicator. Customize height via className.
+
+| Prop      | Type   | Default | Description                                |
+| --------- | ------ | ------- | ------------------------------------------ |
+| className | string | -       | Override default styles (default: `h-1.5`) |
+
+**Default styles**: `bg-muted h-1.5 rounded-full relative flex w-full items-center overflow-x-hidden`
+
+### ProgressIndicator
+
+Visual bar showing task completion. Width automatically adjusts based on parent Progress value.
+
+| Prop      | Type   | Default | Description                                       |
+| --------- | ------ | ------- | ------------------------------------------------- |
+| className | string | -       | Override colors/animation (default: `bg-primary`) |
+
+**Default styles**: `bg-primary h-full transition-all`
+
+Color customization examples:
+
+- Success: `bg-green-500 dark:bg-green-400`
+- Warning: `bg-yellow-500 dark:bg-yellow-400`
+- Danger: `bg-red-500 dark:bg-red-400`
+
+### ProgressLabel
+
+Text label for the progress task.
+
+| Prop      | Type      | Default | Description            |
+| --------- | --------- | ------- | ---------------------- |
+| className | string    | -       | Additional CSS classes |
+| children  | ReactNode | -       | Label text             |
+
+**Default styles**: `text-sm font-medium`
+
+### ProgressValue
+
+Displays formatted progress value (e.g., "65%").
+
+| Prop      | Type                                                            | Default | Description               |
+| --------- | --------------------------------------------------------------- | ------- | ------------------------- |
+| className | string                                                          | -       | Additional CSS classes    |
+| children  | (formatted: string \| null, value: number \| null) => ReactNode | -       | Custom formatter function |
+
+**Default styles**: `text-muted-foreground ml-auto text-sm tabular-nums`
+
+## Data Attributes
+
+All components share these data attributes for styling:
+
+| Attribute          | When Present                      |
+| ------------------ | --------------------------------- |
+| data-progressing   | Value is between min and max      |
+| data-complete      | Value equals max (100 by default) |
+| data-indeterminate | Value is null (unknown duration)  |
+
+## Examples
+
+### Basic Progress
+
+```tsx
+<Progress value={65}>
+  <ProgressLabel>Loading</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+### Minimal (No Label/Value)
+
+```tsx
+<Progress value={45}>
+  <ProgressTrack>
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+### Semantic Colors for States
+
+```tsx
+// Success state (healthy usage)
+<Progress value={45}>
+  <ProgressLabel>API Usage</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator className="bg-green-500 dark:bg-green-400" />
+  </ProgressTrack>
+</Progress>
+
+// Warning state (approaching limit)
+<Progress value={78}>
+  <ProgressLabel>Rate Limit</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator className="bg-yellow-500 dark:bg-yellow-400" />
+  </ProgressTrack>
+</Progress>
+
+// Critical state
+<Progress value={94}>
+  <ProgressLabel>Storage</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator className="bg-red-500 dark:bg-red-400" />
+  </ProgressTrack>
+</Progress>
+```
+
+### Size Variants
+
+```tsx
+// Small
+<Progress value={65}>
+  <ProgressLabel>Small</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack className="h-1">
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+
+// Default
+<Progress value={65}>
+  <ProgressLabel>Default</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack className="h-1.5">
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+
+// Large
+<Progress value={65}>
+  <ProgressLabel>Large</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack className="h-3">
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+### Indeterminate State
+
+For tasks with unknown duration:
+
+```tsx
+<Progress value={null}>
+  <ProgressLabel>Processing...</ProgressLabel>
+  <ProgressTrack>
+    <ProgressIndicator className="w-1/3 animate-pulse" />
+  </ProgressTrack>
+</Progress>
+```
+
+### API Usage Dashboard Context
+
+```tsx
+<div className="border-border bg-card rounded-lg border p-5">
+  <div className="mb-4 flex items-start justify-between">
+    <div className="flex items-center gap-3">
+      <div className="bg-primary/10 text-primary rounded-md p-2">
+        <ActivityIcon className="size-5" />
+      </div>
+      <div>
+        <p className="font-medium">Monthly API Calls</p>
+        <p className="text-muted-foreground text-sm">
+          Standard Plan: 1M requests/month
+        </p>
+      </div>
+    </div>
+    <span className="rounded-full bg-green-500/10 px-2.5 py-1 text-xs font-medium text-green-600">
+      Healthy
+    </span>
+  </div>
+
+  <Progress value={45}>
+    <ProgressLabel>API Requests</ProgressLabel>
+    <ProgressValue />
+    <ProgressTrack>
+      <ProgressIndicator className="bg-green-500 dark:bg-green-400" />
+    </ProgressTrack>
+  </Progress>
+
+  <p className="text-muted-foreground mt-2 text-sm">
+    450,000 of 1,000,000 requests used
+  </p>
+</div>
+```
+
+## Accessibility
+
+- Uses `role="progressbar"` with proper ARIA attributes
+- Announces progress value and label to screen readers
+- Supports `aria-valuetext` for custom accessible labels
+- `getAriaValueText` prop allows dynamic accessible descriptions
+- Indeterminate state properly announced when `value={null}`
+
+## Related
+
+- **Skeleton** - Loading placeholders for content
+- **Spinner** - Circular loading indicator
+- **Badge** - Status indicators with semantic colors