@minidev.fun/ui 1.0.1

package/llm/components/toggle-group.llm.md

@@ -0,0 +1,229 @@
+# ToggleGroup
+
+A group of toggle buttons that share state, commonly used for formatting toolbars, view switchers, and filter controls.
+
+## Import
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@minidev.fun/ui/toggle-group";
+```
+
+## Anatomy
+
+```tsx
+<ToggleGroup>
+  <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
+  <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
+  <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Components
+
+| Component       | Description                                         |
+| --------------- | --------------------------------------------------- |
+| ToggleGroup     | Root container that manages shared state and layout |
+| ToggleGroupItem | Individual toggle button within the group           |
+
+## Props
+
+### ToggleGroup
+
+Inherits all props from `@base-ui/react/toggle-group` plus variant styling props.
+
+| Prop          | Type                         | Default        | Description                                    |
+| ------------- | ---------------------------- | -------------- | ---------------------------------------------- |
+| value         | `any[]`                      | -              | Controlled state: array of pressed item values |
+| defaultValue  | `any[]`                      | -              | Uncontrolled initial state                     |
+| onValueChange | `(value: any[]) => void`     | -              | Called when selection changes                  |
+| multiple      | `boolean`                    | `true`         | Allow multiple items to be pressed             |
+| variant       | `"default" \| "outline"`     | -              | Visual style inherited by all items            |
+| size          | `"default" \| "sm" \| "lg"`  | -              | Size variant inherited by all items            |
+| spacing       | `number`                     | `0`            | Gap between items (0 = joined buttons)         |
+| orientation   | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction                               |
+| disabled      | `boolean`                    | `false`        | Disable all toggles in the group               |
+| loopFocus     | `boolean`                    | `true`         | Wrap focus when reaching end with arrow keys   |
+
+**Note:** By default, `multiple={true}` allows multiple selections. Set `multiple={false}` for single selection mode.
+
+### ToggleGroupItem
+
+Inherits variant and size from parent ToggleGroup context unless explicitly overridden.
+
+| Prop       | Type                        | Default             | Description                                   |
+| ---------- | --------------------------- | ------------------- | --------------------------------------------- |
+| value      | `string`                    | -                   | **Required.** Unique identifier for this item |
+| variant    | `"default" \| "outline"`    | Inherits from group | Override group variant                        |
+| size       | `"default" \| "sm" \| "lg"` | Inherits from group | Override group size                           |
+| aria-label | `string`                    | -                   | Required for icon-only buttons                |
+
+## Data Attributes
+
+### ToggleGroup
+
+| Attribute        | When Present                           |
+| ---------------- | -------------------------------------- |
+| data-orientation | Always: `"horizontal"` or `"vertical"` |
+| data-disabled    | Group is disabled                      |
+| data-multiple    | Multiple selection is enabled          |
+| data-spacing     | Always: spacing value                  |
+| data-variant     | Always: variant name                   |
+| data-size        | Always: size name                      |
+
+### ToggleGroupItem
+
+| Attribute     | When Present             |
+| ------------- | ------------------------ |
+| data-pressed  | Item is in pressed state |
+| data-disabled | Item is disabled         |
+
+## Variants
+
+### Visual Variants
+
+| Variant | Appearance                                     |
+| ------- | ---------------------------------------------- |
+| default | Transparent background, fills on press         |
+| outline | Border with shadow, subtle background on press |
+
+### Sizes
+
+| Size    | Height | Min Width | Padding |
+| ------- | ------ | --------- | ------- |
+| sm      | 32px   | 32px      | 6px     |
+| default | 36px   | 36px      | 8px     |
+| lg      | 40px   | 40px      | 10px    |
+
+## Examples
+
+### Single Selection (Time Range Picker)
+
+```tsx
+function TimeRangePicker() {
+  const [range, setRange] = useState(["7d"]);
+
+  return (
+    <ToggleGroup
+      value={range}
+      onValueChange={(value) => {
+        if (value) setRange(value);
+      }}
+      variant="outline"
+      spacing={0}
+    >
+      <ToggleGroupItem value="1d">1D</ToggleGroupItem>
+      <ToggleGroupItem value="7d">7D</ToggleGroupItem>
+      <ToggleGroupItem value="30d">30D</ToggleGroupItem>
+      <ToggleGroupItem value="90d">90D</ToggleGroupItem>
+    </ToggleGroup>
+  );
+}
+```
+
+### Multiple Selection (Text Formatting)
+
+```tsx
+function TextFormatting() {
+  return (
+    <ToggleGroup variant="outline" spacing={0}>
+      <ToggleGroupItem value="bold" aria-label="Bold">
+        <BoldIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="italic" aria-label="Italic">
+        <ItalicIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="underline" aria-label="Underline">
+        <UnderlineIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  );
+}
+```
+
+### View Switcher (Icon-Only)
+
+```tsx
+function ViewSwitcher() {
+  const [view, setView] = useState(["grid"]);
+
+  return (
+    <ToggleGroup
+      value={view}
+      onValueChange={(value) => {
+        if (value) setView(value);
+      }}
+      variant="outline"
+      spacing={0}
+    >
+      <ToggleGroupItem value="grid" aria-label="Grid view">
+        <GridIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="list" aria-label="List view">
+        <ListIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  );
+}
+```
+
+### Vertical Layout with Spacing
+
+```tsx
+<ToggleGroup orientation="vertical" spacing={2} variant="outline">
+  <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
+  <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
+  <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
+</ToggleGroup>
+```
+
+### Separated Buttons (Spacing > 0)
+
+```tsx
+<ToggleGroup variant="outline" spacing={4}>
+  <ToggleGroupItem value="filter1">Active</ToggleGroupItem>
+  <ToggleGroupItem value="filter2">Pending</ToggleGroupItem>
+  <ToggleGroupItem value="filter3">Archived</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Keyboard Navigation
+
+| Key                    | Action                                               |
+| ---------------------- | ---------------------------------------------------- |
+| Tab                    | Focus the group (first/last item based on direction) |
+| ArrowRight / ArrowDown | Move focus to next item                              |
+| ArrowLeft / ArrowUp    | Move focus to previous item                          |
+| Space / Enter          | Toggle the focused item                              |
+| Home                   | Focus first item                                     |
+| End                    | Focus last item                                      |
+
+Arrow key direction depends on `orientation`: horizontal uses Left/Right, vertical uses Up/Down.
+
+## Accessibility
+
+- Uses `role="group"` for the container
+- Each toggle uses `aria-pressed` to indicate state
+- Icon-only buttons **must** include `aria-label`
+- Keyboard navigation follows ARIA authoring practices
+- Focus management automatically handles arrow key navigation
+
+## Styling Notes
+
+### Joined Buttons (spacing=0)
+
+When `spacing={0}`, items are visually joined:
+
+- First item keeps left border radius (or top for vertical)
+- Middle items have no border radius
+- Last item keeps right border radius (or bottom for vertical)
+- Outline variant: middle items share borders (no duplicate borders)
+
+### Context Inheritance
+
+Items automatically inherit `variant` and `size` from the parent ToggleGroup via React context. You can override these per-item if needed.
+
+## Related
+
+- [Toggle](./toggle.llm.md) - Single toggle button
+- [Button](./button.llm.md) - Standard button component
+- [RadioGroup](./radio-group.llm.md) - Radio button groups

package/llm/components/toggle.llm.md

@@ -0,0 +1,224 @@
+# Toggle
+
+Two-state button that can be pressed (on) or unpressed (off).
+
+## Import
+
+```tsx
+import { Toggle } from "@minidev.fun/ui/toggle";
+```
+
+## Anatomy
+
+```tsx
+<Toggle>
+  <Icon />
+  Label
+</Toggle>
+```
+
+## Props
+
+### Toggle
+
+Extends `@base-ui/react/toggle` Props with additional variant styling.
+
+| Prop            | Type                       | Default   | Description                          |
+| --------------- | -------------------------- | --------- | ------------------------------------ |
+| pressed         | boolean                    | -         | Controlled pressed state             |
+| defaultPressed  | boolean                    | false     | Uncontrolled default pressed state   |
+| onPressedChange | (pressed: boolean) => void | -         | Called when pressed state changes    |
+| disabled        | boolean                    | false     | Whether toggle is disabled           |
+| variant         | "default" \| "outline"     | "default" | Visual style variant                 |
+| size            | "sm" \| "default" \| "lg"  | "default" | Toggle size                          |
+| children        | ReactNode                  | -         | Toggle content (icon, text, or both) |
+| className       | string                     | -         | Additional CSS classes               |
+| render          | ReactElement \| function   | -         | Custom render prop                   |
+
+### Variant Details
+
+**variant="default"**: Transparent background, shows pressed state with muted background.
+
+**variant="outline"**: Border with shadow, more prominent visual separation.
+
+## Data Attributes
+
+| Attribute     | When Present                     |
+| ------------- | -------------------------------- |
+| data-pressed  | Toggle is in pressed state       |
+| data-disabled | Toggle is disabled               |
+| aria-pressed  | "true" or "false" based on state |
+
+## Variants
+
+| Variant | Options          |
+| ------- | ---------------- |
+| variant | default, outline |
+| size    | sm, default, lg  |
+
+## Examples
+
+### Basic Toggle
+
+```tsx
+function BasicExample() {
+  const [pressed, setPressed] = useState(false);
+
+  return (
+    <Toggle pressed={pressed} onPressedChange={setPressed}>
+      Toggle me
+    </Toggle>
+  );
+}
+```
+
+### Icon-Only Toggle
+
+```tsx
+import { BoldIcon } from "lucide-react";
+
+function IconToggle() {
+  return (
+    <Toggle aria-label="Toggle bold">
+      <BoldIcon />
+    </Toggle>
+  );
+}
+```
+
+### Icon with Text
+
+```tsx
+import { GridIcon, ListIcon } from "lucide-react";
+
+function ViewModeToggle() {
+  const [viewMode, setViewMode] = useState<"grid" | "list">("grid");
+
+  return (
+    <div className="flex gap-2">
+      <Toggle
+        pressed={viewMode === "grid"}
+        onPressedChange={(pressed) => pressed && setViewMode("grid")}
+        aria-label="Grid view"
+      >
+        <GridIcon />
+        Grid
+      </Toggle>
+      <Toggle
+        pressed={viewMode === "list"}
+        onPressedChange={(pressed) => pressed && setViewMode("list")}
+        aria-label="List view"
+      >
+        <ListIcon />
+        List
+      </Toggle>
+    </div>
+  );
+}
+```
+
+### Formatting Toolbar
+
+```tsx
+import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";
+
+function FormattingToolbar() {
+  const [formatting, setFormatting] = useState({
+    bold: false,
+    italic: false,
+    underline: false,
+  });
+
+  return (
+    <div className="flex gap-2">
+      <Toggle
+        size="sm"
+        variant="outline"
+        pressed={formatting.bold}
+        onPressedChange={(pressed) =>
+          setFormatting((prev) => ({ ...prev, bold: pressed }))
+        }
+        aria-label="Toggle bold"
+      >
+        <BoldIcon />
+      </Toggle>
+      <Toggle
+        size="sm"
+        variant="outline"
+        pressed={formatting.italic}
+        onPressedChange={(pressed) =>
+          setFormatting((prev) => ({ ...prev, italic: pressed }))
+        }
+        aria-label="Toggle italic"
+      >
+        <ItalicIcon />
+      </Toggle>
+      <Toggle
+        size="sm"
+        variant="outline"
+        pressed={formatting.underline}
+        onPressedChange={(pressed) =>
+          setFormatting((prev) => ({ ...prev, underline: pressed }))
+        }
+        aria-label="Toggle underline"
+      >
+        <UnderlineIcon />
+      </Toggle>
+    </div>
+  );
+}
+```
+
+### Theme Toggle
+
+```tsx
+import { SunIcon, MoonIcon } from "lucide-react";
+
+function ThemeToggle() {
+  const [theme, setTheme] = useState<"light" | "dark">("light");
+
+  return (
+    <div className="flex gap-2">
+      <Toggle
+        variant="outline"
+        pressed={theme === "light"}
+        onPressedChange={(pressed) => pressed && setTheme("light")}
+        aria-label="Light theme"
+      >
+        <SunIcon />
+        Light
+      </Toggle>
+      <Toggle
+        variant="outline"
+        pressed={theme === "dark"}
+        onPressedChange={(pressed) => pressed && setTheme("dark")}
+        aria-label="Dark theme"
+      >
+        <MoonIcon />
+        Dark
+      </Toggle>
+    </div>
+  );
+}
+```
+
+## Keyboard
+
+| Key   | Action               |
+| ----- | -------------------- |
+| Space | Toggle pressed state |
+| Enter | Toggle pressed state |
+
+## Accessibility
+
+- Renders semantic `<button>` element with `aria-pressed` attribute
+- Icons automatically sized to 16px (size-4) unless custom size class provided
+- Always provide `aria-label` when using icon-only toggles
+- Disabled state prevents all interaction and reduces opacity
+- Focus visible ring indicates keyboard focus
+
+## Related
+
+- [Button](./button.llm.md) - For actions instead of state toggles
+- [Checkbox](./checkbox.llm.md) - For form selections
+- [Switch](./switch.llm.md) - For on/off settings

package/llm/components/tooltip.llm.md

@@ -0,0 +1,196 @@
+# Tooltip
+
+Displays contextual information on hover or focus.
+
+## Import
+
+```tsx
+import {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+} from "@minidev.fun/ui/tooltip";
+```
+
+## Anatomy
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>Hover me</TooltipTrigger>
+  <TooltipContent>Helpful information</TooltipContent>
+</Tooltip>
+```
+
+## Components
+
+| Component       | Description                                                               |
+| --------------- | ------------------------------------------------------------------------- |
+| Tooltip         | Root container, manages open state automatically                          |
+| TooltipTrigger  | Element that shows tooltip on hover/focus                                 |
+| TooltipContent  | Popup content with automatic portal, positioning, and arrow               |
+| TooltipProvider | Optional provider for configuring shared delay (auto-included in Tooltip) |
+
+## Props
+
+### Tooltip
+
+| Prop            | Type                           | Default | Description                                       |
+| --------------- | ------------------------------ | ------- | ------------------------------------------------- |
+| defaultOpen     | boolean                        | -       | Whether tooltip is initially open (uncontrolled)  |
+| open            | boolean                        | -       | Controlled open state                             |
+| onOpenChange    | (open: boolean) => void        | -       | Called when open state changes                    |
+| trackCursorAxis | 'none' \| 'both' \| 'x' \| 'y' | 'none'  | Which axis the tooltip should track the cursor on |
+
+### TooltipTrigger
+
+Standard trigger props with `render` prop support. Use `render` to customize:
+
+```tsx
+<TooltipTrigger render={<Button variant="ghost" size="icon" />}>
+  <SettingsIcon />
+</TooltipTrigger>
+```
+
+### TooltipContent
+
+Automatically renders portal with positioner and arrow.
+
+| Prop        | Type                                   | Default  | Description                           |
+| ----------- | -------------------------------------- | -------- | ------------------------------------- |
+| side        | 'top' \| 'bottom' \| 'left' \| 'right' | 'top'    | Which side to position tooltip        |
+| sideOffset  | number                                 | 4        | Distance from trigger in pixels       |
+| align       | 'start' \| 'center' \| 'end'           | 'center' | How to align tooltip relative to side |
+| alignOffset | number                                 | 0        | Offset along alignment axis in pixels |
+| className   | string                                 | -        | Additional CSS classes                |
+
+### TooltipProvider
+
+Only needed when sharing state across multiple tooltips. Tooltip automatically includes provider.
+
+| Prop  | Type   | Default | Description                         |
+| ----- | ------ | ------- | ----------------------------------- |
+| delay | number | 0       | Delay in ms before showing tooltips |
+
+## Data Attributes (for styling)
+
+| Attribute           | When Present                                         |
+| ------------------- | ---------------------------------------------------- |
+| data-open           | Tooltip is open                                      |
+| data-closed         | Tooltip is closed                                    |
+| data-side           | Current side: 'top' \| 'bottom' \| 'left' \| 'right' |
+| data-align          | Current alignment: 'start' \| 'center' \| 'end'      |
+| data-starting-style | Tooltip is animating in                              |
+| data-ending-style   | Tooltip is animating out                             |
+| data-instant        | Animations should be instant                         |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button variant="outline">Hover me</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>This is a tooltip</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Icon Button with Tooltip
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button variant="ghost" size="icon">
+      <SettingsIcon />
+    </Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>Settings</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Placement Options
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button>Show below</Button>
+  </TooltipTrigger>
+  <TooltipContent side="bottom" align="start">
+    <p>Positioned at bottom-start</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### With Keyboard Shortcut
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button variant="outline">Save</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <div className="flex items-center gap-2">
+      <span>Save document</span>
+      <kbd className="bg-background text-foreground rounded border px-1.5 py-0.5 font-mono text-xs">
+        ⌘S
+      </kbd>
+    </div>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Help Icon with Detailed Info
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <button className="text-muted-foreground hover:text-foreground inline-flex items-center transition-colors">
+      <HelpCircleIcon className="size-4" />
+    </button>
+  </TooltipTrigger>
+  <TooltipContent side="top">
+    <p className="max-w-xs">
+      Track your API requests, rate limits, and usage patterns across all your
+      applications.
+    </p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Always Open (Controlled)
+
+```tsx
+<Tooltip defaultOpen>
+  <TooltipTrigger>
+    <Button variant="outline">Always visible</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>This tooltip is always visible</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+## Keyboard
+
+| Key    | Action                     |
+| ------ | -------------------------- |
+| Tab    | Move focus to/from trigger |
+| Escape | Close tooltip              |
+
+## Accessibility
+
+- Automatically adds ARIA attributes for screen readers
+- Tooltip appears on hover and focus for keyboard users
+- Content announced to screen readers when opened
+- Works with disabled elements (tooltip still shows)
+- Arrow provides visual relationship between trigger and content
+
+## Related
+
+- [Popover](./popover.llm.md) - For interactive content requiring click to open
+- [HoverCard](./hover-card.llm.md) - For rich preview content on hover