@minidev.fun/ui 1.0.1

package/llm/components/item.llm.md

@@ -0,0 +1,353 @@
+# Item
+
+Flexible compound component system for building structured list items with media, content, and actions.
+
+## Import
+
+```tsx
+import {
+  Item,
+  ItemGroup,
+  ItemSeparator,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions,
+  ItemHeader,
+  ItemFooter,
+} from "@minidev.fun/ui/item";
+```
+
+## Anatomy
+
+```tsx
+<ItemGroup>
+  <Item>
+    <ItemMedia variant="icon">
+      <Icon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Title</ItemTitle>
+      <ItemDescription>Description text</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button />
+    </ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+## Components
+
+| Component       | Description                                                     |
+| --------------- | --------------------------------------------------------------- |
+| ItemGroup       | Container for organizing related items in a vertical list       |
+| Item            | Root item component, supports `render` prop for custom elements |
+| ItemSeparator   | Horizontal divider between items                                |
+| ItemMedia       | Container for icons, images, or avatars                         |
+| ItemContent     | Main content area that flexes to fill space                     |
+| ItemTitle       | Medium-weight title text with badge support                     |
+| ItemDescription | Secondary description text (truncates at 2 lines)               |
+| ItemActions     | Container for buttons or controls                               |
+| ItemHeader      | Full-width header for complex layouts                           |
+| ItemFooter      | Full-width footer for additional info                           |
+
+## Props
+
+### Item
+
+| Prop    | Type                              | Default   | Description                                           |
+| ------- | --------------------------------- | --------- | ----------------------------------------------------- |
+| variant | "default" \| "outline" \| "muted" | "default" | Visual style variant                                  |
+| size    | "default" \| "sm" \| "xs"         | "default" | Size affecting padding and spacing                    |
+| render  | ReactNode                         | -         | Custom element to render as (e.g., `<a>`, `<button>`) |
+
+### ItemMedia
+
+| Prop    | Type                           | Default   | Description                              |
+| ------- | ------------------------------ | --------- | ---------------------------------------- |
+| variant | "default" \| "icon" \| "image" | "default" | Media type determining sizing and layout |
+
+**Behavior**: Automatically aligns to top when `ItemDescription` is present using CSS container queries.
+
+### ItemGroup
+
+Container with `role="list"` that automatically adjusts gap based on child item sizes:
+
+- `size="default"`: gap-4
+- `size="sm"`: gap-2.5
+- `size="xs"`: gap-2
+
+### render Prop (Item)
+
+Customize the underlying HTML element:
+
+```tsx
+// Render as link
+<Item render={<a href="/profile" />}>
+  <ItemContent>
+    <ItemTitle>View Profile</ItemTitle>
+  </ItemContent>
+</Item>
+
+// Render as button
+<Item render={<button onClick={handleClick} />}>
+  <ItemContent>
+    <ItemTitle>Clickable Item</ItemTitle>
+  </ItemContent>
+</Item>
+```
+
+## Data Attributes
+
+| Attribute                    | When Present | Used By                        |
+| ---------------------------- | ------------ | ------------------------------ |
+| data-slot="item"             | Always       | Item component                 |
+| data-slot="item-media"       | Always       | ItemMedia component            |
+| data-slot="item-content"     | Always       | ItemContent component          |
+| data-slot="item-title"       | Always       | ItemTitle component            |
+| data-slot="item-description" | Always       | ItemDescription component      |
+| data-slot="item-actions"     | Always       | ItemActions component          |
+| data-slot="item-header"      | Always       | ItemHeader component           |
+| data-slot="item-footer"      | Always       | ItemFooter component           |
+| data-slot="item-separator"   | Always       | ItemSeparator component        |
+| data-variant                 | Always       | ItemMedia (icon/image/default) |
+
+## Variants
+
+### Visual Variants
+
+| Variant | Description                                       |
+| ------- | ------------------------------------------------- |
+| default | Clean appearance with transparent border          |
+| outline | Visible border for clear separation               |
+| muted   | Subtle background (bg-muted/50) for grouped items |
+
+### Size Variants
+
+| Size    | Padding     | Gap     | Use Case                        |
+| ------- | ----------- | ------- | ------------------------------- |
+| default | py-3.5 px-4 | gap-3.5 | Regular content, standard lists |
+| sm      | py-2.5 px-3 | gap-2.5 | Compact layouts, sidebars       |
+| xs      | py-2 px-2.5 | gap-2   | Dense lists, activity feeds     |
+
+### Media Variants
+
+| Variant | Size              | Description                                                                 |
+| ------- | ----------------- | --------------------------------------------------------------------------- |
+| default | auto              | Transparent background, flex container                                      |
+| icon    | auto              | Auto-sizes SVG icons to size-4                                              |
+| image   | size-10 (default) | Fixed container with rounded corners, scales to size-8 (sm) and size-6 (xs) |
+
+## Examples
+
+### Basic List Item
+
+```tsx
+<ItemGroup>
+  <Item variant="outline">
+    <ItemMedia variant="icon">
+      <KeyIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>API Key</ItemTitle>
+      <ItemDescription>Production key created 3 months ago</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button variant="ghost" size="icon-sm">
+        <CopyIcon />
+      </Button>
+    </ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+### With Status Badge
+
+```tsx
+<Item variant="outline">
+  <ItemMedia variant="icon">
+    <WebhookIcon className="text-green-500" />
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>
+      Production Webhook
+      <Badge variant="secondary">Active</Badge>
+    </ItemTitle>
+    <ItemDescription>https://minidev.fun</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button variant="ghost">Test</Button>
+  </ItemActions>
+</Item>
+```
+
+### Complex Layout with Header/Footer
+
+```tsx
+<Item variant="muted">
+  <ItemMedia variant="icon">
+    <WebhookIcon />
+  </ItemMedia>
+  <ItemContent>
+    <ItemHeader>
+      <div className="flex flex-col gap-1">
+        <ItemTitle>
+          Staging Webhook
+          <Badge variant="destructive">Failed</Badge>
+        </ItemTitle>
+        <ItemDescription>https://staging.example.com/webhooks</ItemDescription>
+      </div>
+      <ItemActions>
+        <Button variant="ghost">Retry</Button>
+      </ItemActions>
+    </ItemHeader>
+    <ItemFooter className="border-border w-full border-t pt-2">
+      <div className="flex items-center gap-2 text-sm">
+        <XCircleIcon className="text-red-500 size-4" />
+        <span className="text-muted-foreground">
+          Last failure: Connection timeout (5xx)
+        </span>
+      </div>
+    </ItemFooter>
+  </ItemContent>
+</Item>
+```
+
+### Team Member with Avatar
+
+```tsx
+<Item>
+  <ItemMedia variant="icon">
+    <div className="bg-primary/10 text-primary flex size-10 items-center justify-center rounded-full text-sm font-semibold">
+      JD
+    </div>
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>
+      Jane Doe
+      <Badge variant="outline">Owner</Badge>
+    </ItemTitle>
+    <ItemDescription>
+      jane.doe@example.com • Full access to all resources
+    </ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button variant="ghost" size="icon-sm">
+      <MoreHorizontalIcon />
+    </Button>
+  </ItemActions>
+</Item>
+```
+
+### Activity Feed (Compact)
+
+```tsx
+<ItemGroup>
+  <Item size="xs">
+    <ItemMedia variant="icon">
+      <CheckCircle2Icon className="text-green-500 size-4" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>API key created</ItemTitle>
+      <ItemDescription>
+        Production key created by jane.doe@example.com
+      </ItemDescription>
+    </ItemContent>
+    <ItemContent>
+      <div className="text-muted-foreground flex items-center gap-1 text-xs">
+        <ClockIcon className="size-3" />2 hours ago
+      </div>
+    </ItemContent>
+  </Item>
+</ItemGroup>
+```
+
+### Document List with Images
+
+```tsx
+<Item variant="outline">
+  <ItemMedia variant="image">
+    <div className="bg-gradient-to-br from-orange-500 to-yellow-500 flex size-full items-center justify-center">
+      <FileIcon className="text-white size-6" />
+    </div>
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>API Documentation.pdf</ItemTitle>
+    <ItemDescription>Last modified 3 days ago • 2.4 MB</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button variant="ghost">Download</Button>
+    <Button variant="ghost" size="icon-sm">
+      <ChevronRightIcon />
+    </Button>
+  </ItemActions>
+</Item>
+```
+
+### List with Separators
+
+```tsx
+<ItemGroup>
+  <Item variant="muted">
+    <ItemContent>
+      <ItemTitle>First Item</ItemTitle>
+    </ItemContent>
+  </Item>
+
+  <ItemSeparator />
+
+  <Item variant="muted">
+    <ItemContent>
+      <ItemTitle>Second Item</ItemTitle>
+    </ItemContent>
+  </Item>
+</ItemGroup>
+```
+
+## Accessibility
+
+- ItemGroup renders with `role="list"` for semantic list structure
+- Focus ring styles on Item when using `render` prop with interactive elements
+- ItemDescription automatically truncates with `line-clamp-2` to prevent excessive text
+- Links within ItemDescription receive underline and hover styles
+- All interactive elements maintain proper focus indicators
+
+## Composition Patterns
+
+### Multiple Content Areas
+
+Use multiple `ItemContent` components for side-by-side content sections:
+
+```tsx
+<Item>
+  <ItemContent>
+    <ItemTitle>Main Content</ItemTitle>
+    <ItemDescription>Primary description</ItemDescription>
+  </ItemContent>
+  <ItemContent>
+    <div className="text-muted-foreground text-xs">2 hours ago</div>
+  </ItemContent>
+</Item>
+```
+
+The first `ItemContent` flexes to fill space, subsequent ones use `flex-none`.
+
+### Icon with Background
+
+Wrap icons in colored containers for visual emphasis:
+
+```tsx
+<ItemMedia variant="icon">
+  <div className="bg-primary/10 text-primary rounded-md p-2">
+    <KeyIcon className="size-5" />
+  </div>
+</ItemMedia>
+```
+
+## Related
+
+- [Button](/components/button) - For ItemActions controls
+- [Badge](/components/badge) - For status indicators in titles
+- [Separator](/components/separator) - Used by ItemSeparator

package/llm/components/kbd.llm.md

@@ -0,0 +1,263 @@
+# Kbd
+
+Display keyboard shortcuts and key combinations with consistent styling.
+
+## Import
+
+```tsx
+import { Kbd, KbdGroup } from "@minidev.fun/ui/kbd";
+```
+
+## Anatomy
+
+```tsx
+// Single key
+<Kbd>K</Kbd>
+
+// Key combination
+<KbdGroup>
+  <Kbd><CommandIcon /></Kbd>
+  <Kbd>K</Kbd>
+</KbdGroup>
+```
+
+## Components
+
+| Component | Description                                                 |
+| --------- | ----------------------------------------------------------- |
+| Kbd       | Individual keyboard key display (text or icon)              |
+| KbdGroup  | Container for multiple keys pressed together or in sequence |
+
+## Props
+
+### Kbd
+
+Extends standard HTML `<kbd>` element props.
+
+| Prop      | Type      | Default | Description                                     |
+| --------- | --------- | ------- | ----------------------------------------------- |
+| children  | ReactNode | -       | Key text or icon (e.g., "K", `<CommandIcon />`) |
+| className | string    | -       | Additional CSS classes                          |
+
+**Auto-styling:**
+
+- Fixed height (h-5), auto width with minimum size
+- Muted background and foreground colors
+- Non-interactive (pointer-events-none, select-none)
+- Icons auto-sized to size-3
+- Special styling when used in tooltips
+
+### KbdGroup
+
+Extends standard HTML `<div>` element props (rendered as `<kbd>` tag).
+
+| Prop      | Type      | Default | Description                 |
+| --------- | --------- | ------- | --------------------------- |
+| children  | ReactNode | -       | Multiple `<Kbd>` components |
+| className | string    | -       | Additional CSS classes      |
+
+**Auto-behaviors:**
+
+- Horizontal flex layout with gap-1
+- Use for simultaneous keys (Cmd+K) or sequential keys (G→H)
+
+## Data Attributes
+
+| Attribute             | Component | Description                          |
+| --------------------- | --------- | ------------------------------------ |
+| data-slot="kbd"       | Kbd       | Identifies individual key element    |
+| data-slot="kbd-group" | KbdGroup  | Identifies key combination container |
+
+## Examples
+
+### Single Keys
+
+```tsx
+<div className="flex gap-2">
+  <Kbd>A</Kbd>
+  <Kbd>Esc</Kbd>
+  <Kbd>Enter</Kbd>
+  <Kbd>Space</Kbd>
+</div>
+```
+
+### Keys with Icons
+
+```tsx
+import { CommandIcon, ArrowUpIcon, CornerDownLeftIcon } from "lucide-react";
+
+<div className="flex gap-2">
+  <Kbd>
+    <CommandIcon />
+  </Kbd>
+  <Kbd>
+    <ArrowUpIcon />
+  </Kbd>
+  <Kbd>
+    <CornerDownLeftIcon />
+  </Kbd>
+</div>;
+```
+
+Icons are automatically sized to fit the kbd container.
+
+### Key Combinations (Simultaneous)
+
+```tsx
+// Cmd+K (command palette)
+<KbdGroup>
+  <Kbd><CommandIcon /></Kbd>
+  <Kbd>K</Kbd>
+</KbdGroup>
+
+// Cmd+Shift+P
+<KbdGroup>
+  <Kbd><CommandIcon /></Kbd>
+  <Kbd>Shift</Kbd>
+  <Kbd>P</Kbd>
+</KbdGroup>
+
+// Ctrl+Alt+Delete
+<KbdGroup>
+  <Kbd>Ctrl</Kbd>
+  <Kbd>Alt</Kbd>
+  <Kbd><DeleteIcon /></Kbd>
+</KbdGroup>
+```
+
+### Sequential Keys (Vim-like)
+
+```tsx
+// G then H (Go Home)
+<KbdGroup>
+  <Kbd>G</Kbd>
+  <Kbd>H</Kbd>
+</KbdGroup>
+
+// G then D (Go Dashboard)
+<KbdGroup>
+  <Kbd>G</Kbd>
+  <Kbd>D</Kbd>
+</KbdGroup>
+```
+
+KbdGroup works for both simultaneous and sequential shortcuts - context determines meaning.
+
+### In Documentation/Prose
+
+```tsx
+<p>
+  To open the command palette, press{" "}
+  <KbdGroup>
+    <Kbd><CommandIcon /></Kbd>
+    <Kbd>K</Kbd>
+  </KbdGroup>{" "}
+  at any time.
+</p>
+
+<p>
+  Use <Kbd><ArrowUpIcon /></Kbd> and <Kbd><ArrowDownIcon /></Kbd> to navigate,
+  then press <Kbd><CornerDownLeftIcon /></Kbd> to select.
+</p>
+```
+
+### Keyboard Shortcuts Help Panel
+
+```tsx
+function ShortcutsHelp() {
+  const shortcuts = [
+    {
+      keys: (
+        <KbdGroup>
+          <Kbd>
+            <CommandIcon />
+          </Kbd>
+          <Kbd>K</Kbd>
+        </KbdGroup>
+      ),
+      description: "Open command palette",
+    },
+    {
+      keys: (
+        <KbdGroup>
+          <Kbd>
+            <CommandIcon />
+          </Kbd>
+          <Kbd>S</Kbd>
+        </KbdGroup>
+      ),
+      description: "Save changes",
+    },
+    {
+      keys: <Kbd>Esc</Kbd>,
+      description: "Close dialog",
+    },
+  ];
+
+  return (
+    <div className="space-y-2">
+      {shortcuts.map((shortcut, idx) => (
+        <div key={idx} className="flex justify-between">
+          <span>{shortcut.description}</span>
+          {shortcut.keys}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Common Shortcuts Grid
+
+```tsx
+<div className="grid grid-cols-2 gap-4">
+  <div className="flex justify-between">
+    <span>Save</span>
+    <KbdGroup>
+      <Kbd>
+        <CommandIcon />
+      </Kbd>
+      <Kbd>S</Kbd>
+    </KbdGroup>
+  </div>
+  <div className="flex justify-between">
+    <span>Copy</span>
+    <KbdGroup>
+      <Kbd>
+        <CommandIcon />
+      </Kbd>
+      <Kbd>C</Kbd>
+    </KbdGroup>
+  </div>
+  <div className="flex justify-between">
+    <span>Paste</span>
+    <KbdGroup>
+      <Kbd>
+        <CommandIcon />
+      </Kbd>
+      <Kbd>V</Kbd>
+    </KbdGroup>
+  </div>
+  <div className="flex justify-between">
+    <span>Undo</span>
+    <KbdGroup>
+      <Kbd>
+        <CommandIcon />
+      </Kbd>
+      <Kbd>Z</Kbd>
+    </KbdGroup>
+  </div>
+</div>
+```
+
+## Accessibility
+
+- Uses semantic `<kbd>` HTML element for keyboard input
+- Non-interactive by default (pointer-events-none, select-none)
+- Text content is screen-reader accessible
+- Icon-only keys may need aria-label on parent for context
+
+## Related
+
+- [Tooltip](/docs/components/tooltip.llm.md) - Often used together to show shortcuts on hover
+- [Command](/docs/components/command.llm.md) - Command palette that displays kbd shortcuts